Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Outpost

An Outpost runs inside your network and connects Teleskope to data sources your Teleskope environment cannot reach directly, including private file shares and on-premise databases. Choose Thin, Resident + GPU, or Resident + CPU based on where you want scanning to run and the hardware available.

See Architecture and Data Flow for the full platform architecture, including cloud and SaaS connectors.

Choose a deployment model

Model
Choose it when
Where parsing and classification run

Thin

You want a small host for private connectivity, and file content or database results can be processed in your Teleskope environment. Supports SMB and NFS file shares and on-premise SQL.

In your Teleskope environment. The Outpost reads sources locally and streams the data over TLS.

Resident + GPU

You want file-share content parsed and classified inside your network, with GPU acceleration.

On the Outpost, using an NVIDIA GPU.

Resident + CPU

You want file-share content parsed and classified inside your network, but do not have a GPU. CPU classification is slower than GPU classification.

On the Outpost's processors.

All three models use an agent installed as a systemd service and are managed from Settings → Outposts. Resident models also run local processing containers. Resident currently supports local file-share scanning; use Thin for database row sampling and classification.

Thin and Resident models can share a Teleskope environment.

Security and data flow

The Outpost opens connections to your data sources from inside your network. It connects outbound to your Teleskope environment using a WebSocket over TLS (wss://) on port 443 to receive work and report results. Teleskope does not need an inbound path to the Outpost or your source systems.

Outpost architecture: Thin reads file shares and databases locally and sends content to Teleskope for processing; Resident parses and classifies file shares locally using a GPU or CPU and reports results over outbound TLS.
Model
What leaves your network

Thin

File content being scanned, database results, resource metadata, findings, and the agent's logs and metrics.

Resident + GPU or CPU

Resource metadata, classification findings, fingerprints, scan status, and the agent's logs and metrics. Metadata can include file names, paths, owners, permissions, and tabular column headers. File content is parsed and classified locally, and file preview is disabled.

Metadata and findings can themselves contain sensitive information. Thin supports requested file previews, which can return matched context to Observatory.

Each Outpost authenticates with its own key. Data-source credentials are supplied over the encrypted connection with the work that needs them. The service runs as the unprivileged teleskope-outpost user; Resident processing containers also run without root privileges.

The host's policy limits which data-source networks the Outpost may access. Only an operator on the host can change that policy. By default, it permits the RFC 1918 private address ranges.

Prerequisites

Host requirements

All models require a dedicated x86_64 (amd64) Linux host with systemd, root or sudo access for installation, working DNS resolution, and accurate system time.

Requirement
Thin
Resident + GPU
Resident + CPU

Operating system

Ubuntu or Debian; RHEL 9, Rocky Linux 9, or AlmaLinux 9. Suggested versions: Ubuntu 22.04/24.04 or Debian 12.

Ubuntu 24.04 recommended

Ubuntu 24.04 recommended

CPU

2 vCPU

8 vCPU recommended

At least 8 vCPU; 16 recommended. AVX2 required.

Memory

1 GB

32 GB recommended

At least 30 GiB available to the OS

Disk

2 GB

200 GB recommended for Outpost state; at least 100 GB free at /var/lib/teleskope-outpost before installation

200 GB recommended for Outpost state; at least 100 GB free at /var/lib/teleskope-outpost before installation

GPU

Not required

NVIDIA T4 class or newer with 16 GB VRAM, compute capability 7.5 or newer, NVIDIA driver 580 or newer, and NVIDIA Container Toolkit installed

Not required

Ubuntu 24.04 is the recommended release for Resident. Ubuntu 26.04 has also been verified with the installer's --force option.

These values are a baseline. Teleskope confirms final sizing from your data volume, schedule, and classification model. A release may enforce additional requirements.

Before running the install command

  • Have a Teleskope administrator open Settings → Outposts. If the page is missing, contact your Teleskope team.

  • Ensure curl, sha256sum, useradd, usermod, getent, journalctl, and setpriv are installed.

  • For Resident + GPU, install the NVIDIA driver and NVIDIA Container Toolkit first, and confirm nvidia-smi can see the GPU.

  • For either Resident model, ensure Ubuntu package repositories are reachable. The installer installs Podman and uidmap if Podman is absent; an existing Podman installation must be version 4.3 or newer and have uidmap available.

Ubuntu images, including official Ubuntu cloud images, can use HTTP package mirrors. An outbound-443-only firewall will block those downloads. Before installation, configure approved HTTPS package mirrors or allow outbound TCP 80 to your package mirrors, and confirm sudo apt-get update succeeds.

The one-time install token is consumed before the installer installs Podman. If package installation then fails, fix repository access and generate a fresh install command before retrying.

Network requirements

All connections are initiated by the Outpost. No inbound firewall rule is required. Outbound connections to Teleskope and its artifact store use TCP 443; source access and package downloads have their own requirements below.

Destination
Port
Required when
Purpose

Your environment's Outposts endpoint, the host in the generated install command

443

All models

Installation and the encrypted connection to Teleskope

Teleskope's artifact and diagnostics storage on Amazon S3

443

Installation, upgrades, and diagnostic collection

Release and Resident image downloads; requested diagnostic uploads

Your OS package mirrors

443 for HTTPS; 80 if configured for HTTP

Installing missing packages, including Resident's Podman dependencies

Package downloads

NVIDIA package repositories

443, with any package-mirror access required by your OS

Preparing a Resident + GPU host

NVIDIA driver and Container Toolkit installation

Your DNS servers

53

All models

Resolving Teleskope endpoints and source hostnames

Your file servers

445

SMB scanning

File share access

Your Kerberos KDCs

88 (TCP and UDP)

SMB with Kerberos authentication

Ticket requests. Keep the host clock within five minutes of the KDC.

Your NFS servers

111, 2049, and the server's mountd port (often 20048)

NFS scanning

NFSv3 access; no host filesystem mount is required

Your NetApp ONTAP management address

443

Shares enrolled through the ONTAP API

File content, share and permission metadata

Your database servers

Database port

On-premise SQL through Thin

Normally 3306 for MySQL, 5432 for PostgreSQL, 1433 for SQL Server, or 1521 for Oracle

Your Teleskope team provides the exact external hostnames for your allowlist. After installation, /etc/teleskope/policy.toml records the Teleskope and storage endpoints. Also ensure your data-source addresses are permitted by the host policy.

Install

  1. Prepare the host and network using the prerequisites above. In Teleskope, go to Settings → Outposts and select Add outpost.

  2. Enter a name and optional description. Choose the model:

    Deployment model
    Mode
    Classifier

    Thin

    Thin

    Not applicable

    Resident + GPU

    Resident

    GPU

    Resident + CPU

    Resident

    CPU

  3. Select Generate install command, then copy the command. It is shown once, expires after 24 hours, and can be used only once. Keep it private.

  4. Run the generated command on the prepared host as a user with sudo. The command includes the correct mode and classifier options. To inspect the script first, download the script URL from that command and run it with the same arguments:

    For Resident + GPU, retain --mode resident. For Resident + CPU, retain both --mode resident --classifier cpu:

    The installer checks the host, exchanges the token for an Outpost key, verifies the release download, writes the host policy, and starts the outpost-crawler service. Resident also prepares its local container runtime and downloads the processing images. Allow for an initial download of approximately 21 GB.

  5. Wait for the Outpost to show Available on the Outposts page. Resident may show Installing while images download and Starting while its components become healthy. Initial registration alone does not mean scanning is ready. On the host, check:

  6. Assign data sources. When enrolling a file share or on-premise SQL host, select this Outpost and use the server address as the Outpost host sees it. See File Systems and On-Premise SQL. Use Thin for database classification.

  7. Open the Outpost's details and select Check connectivity, then run the connector's Test Connection. Confirm a scan completes and results appear in Teleskope; a connected agent alone does not prove source access or successful scanning.

If a command expires or an installation fails after its token is consumed, use Add outpost with the same name to generate a replacement before the Outpost connects. This retires the previous command. If the Outpost has already connected, contact your Teleskope team before reinstalling it.

Host policy

The installer writes /etc/teleskope/policy.toml. It is owned by root and editable only on the host. The agent rereads changes without a restart.

Setting
Purpose

connector_networks

Address ranges the Outpost may access for data sources and connectivity checks. Defaults to 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16. Narrow these to your source networks where possible.

upgrades

auto applies an offered upgrade immediately; window waits for a weekly window; manual waits for approval on the host.

window

Upgrade window in UTC, for example Sat 02:00-06:00 UTC.

pinned_version

Restricts upgrades to a specific release when set.

For example, append these options to the generated install command to limit source access and schedule upgrades:

An invalid policy causes the agent to refuse data-source work and upgrades until the file is corrected. A reinstall preserves your upgrade policy and connector network settings unless you supply options to change them.

Update

From the Outpost's details on Settings → Outposts, an administrator can Rotate key, Check connectivity, Collect diagnostics, or Upgrade outpost. The page also shows recent actions and settings for logging and concurrency.

Select Upgrade outpost to offer the latest release. The agent verifies the download and applies it according to the host policy. With upgrades = "manual", approve the waiting release on the host:

Agent upgrades roll back to the previous release if the new agent repeatedly fails to start or does not register within five minutes. After a Resident upgrade, also confirm its processing components are healthy and the Outpost returns to Available.

Host command
Purpose

teleskope-outpost status

Show the connection, release, mode, policy, and last error

sudo teleskope-outpost pause

Pause scans and crawls and refuse new work; file actions already accepted may finish

sudo teleskope-outpost resume

Resume work

sudo teleskope-outpost upgrade deny

Decline a waiting upgrade

sudo teleskope-outpost diagnostics show

Inspect what the last diagnostic bundle contained

journalctl -u outpost-crawler -f

Follow the agent's local logs

Monitoring

The agent forwards its own logs and metrics to Teleskope over its encrypted connection. Requested diagnostic bundles include recent logs, settings with the key removed, host details, connectivity results, and audit entries. Use Collect diagnostics and Download diagnostics on the Outposts page when working with your Teleskope team.

To stop forwarding agent logs or metrics, set HUB_LOG_FORWARD=false or HUB_METRICS_FORWARD=false in /etc/teleskope/outpost-crawler.env, then run sudo systemctl restart outpost-crawler. Required product traffic, including work, results, and heartbeats, continues.

Troubleshooting

Symptom
Cause and fix

Install command was already used or has expired

Generate a fresh command. A token can already be spent even if a later installation step failed.

Resident installation fails at apt-get update or Podman installation

Check package-mirror access. Use HTTPS mirrors or permit port 80 to HTTP mirrors, then generate a fresh command.

Resident rejects the OS

Use the recommended Ubuntu 24.04 release, or add --force when installing on verified Ubuntu 26.04.

Resident reports insufficient disk

Ensure at least 100 GB is free at /var/lib/teleskope-outpost. Provision 200 GB for download and upgrade headroom.

CPU checks fail

Confirm at least 8 vCPU, 30 GiB of OS-visible memory, and AVX2 support.

GPU checks fail

Check nvidia-smi, GPU memory, driver version, and NVIDIA Container Toolkit against the host requirements.

Outpost stays Waiting, Installing, Starting, or Degraded

Check teleskope-outpost status and journalctl -u outpost-crawler. For Resident, inspect component health in Teleskope and confirm image downloads can reach the artifact store.

Installer or agent cannot connect to Teleskope

Check DNS, system time, CA certificates, and outbound 443 to the generated command's endpoint.

Address is outside the Outpost's connector networks

Add the source's range to the host policy, or use the address the Outpost should access.

Data-source connection times out

Check DNS and firewall rules from the Outpost to the source port.

Kerberos authentication fails

Sync the host clock, allow TCP and UDP 88 to the KDC, and enter the realm in uppercase.

Upgrade waits for approval or a window

Check the host policy; approve a manual upgrade or wait for its configured window.

For anything else, reach out to your Teleskope representative or email contact@teleskope.ai.

PreviousArchitecture and Data Flow
NextRole Based Access Control

Last updated

Was this helpful?