Tentacle Deployment and Networking
A Tentacle connects a host to a Cracken Realm and runs the tools used by your operations. Deploy it with the generated installer, Docker Compose, Docker, Podman, or a native LOTL binary. You can also control how its security tooling reaches an authorized target by using the assessment host's route, a customer-provided proxy, or a WireGuard tunnel.
At a glance
- Deploy from the Realm wizard — use the recommended one-line installer or copy a generated Docker Compose, Docker run, or Podman run artifact.
- Configure egress in the install flow — Cracken bakes the selected networking settings into the generated command.
- Choose the required level of routing control — a proxy supplies compatible applications with an approved route; WireGuard supplies an enforced network path.
- Keep the operation workflow consistent — configure network placement once, then use tools, Vessels, terminals, and browser sessions from Cracken.
- Generate an updated artifact — changing advanced settings produces a replacement command for the host without silently changing the operation workflow.
- Only me travels with the command too — turning it on for the install also replaces the generated command; see Keep a Tentacle to yourself.
Deploy from Realm onboarding
When you create a Realm, the onboarding flow generates a deployment command tied to that Realm. The same choices are available when you add another Tentacle later. Sandbox is the recommended option and runs the Tentacle in Docker or Podman. LOTL supplies a checksum-verified native binary for an administrator-managed service with no container isolation. Covert deployments are enabled with your Cracken account team. Turning on Only me replaces the generated command with one whose credential locks the Tentacle to you; see Keep a Tentacle to yourself.
The generated command contains a time-limited enrollment credential. Treat the entire command as a secret: copy it only to the intended assessment host, do not place it in shell history shared by other users, and do not paste it into tickets or operation output.
Recommended script installer
The default onboarding screen shows the right one-line installer for the selected shell. It detects and configures the supported container runtime, downloads the generated deployment assets, starts the Tentacle, and prints its lifecycle commands.
Linux, macOS, and WSL command shape:
curl -fsSL <generated-installer-url> | sh
Windows PowerShell command shape:
iwr -useb <generated-installer-url> -OutFile .\tentacle.ps1; .\tentacle.ps1 -Yes
If the command downloads tentacle.ps1 but PowerShell reports that running scripts is disabled,
allow scripts for the current PowerShell session and run the downloaded installer again:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\tentacle.ps1 -Yes
The process-scoped setting is removed when you close the PowerShell session. An organization-managed Group Policy can override it; contact your administrator if the script remains blocked.
Always copy the generated version shown in Cracken. A self-hosted deployment uses its own Cracken host, and every generated command carries the correct Realm credential and deployment settings.
For LOTL, download the platform binary. Your administrator must provide the credential environment, register the OS service, and retain the service lifecycle commands. The download alone does not connect a Tentacle. Cracken verifies the release before download and installation, and the service applies verified updates automatically.
Advanced Sandbox options
Expand Advanced options when you need the generated container assets directly:
| Option | What to copy and run |
|---|---|
| Script | Use the Linux, macOS, or Windows installer shown above. |
| Docker Compose | Download the generated docker-compose.yaml, keep it in the current directory, then copy and run the generated Compose command. |
| Docker run | Copy the complete generated Docker block. It already includes the image, credential, runtime settings, and registry login when one is required. |
| Podman run | Copy the complete generated Podman block. It carries the same deployment-specific settings as the Docker command. |
The Compose command ends with:
docker compose up -d
The standalone command shapes are:
<generated registry login, when required> && \
docker run <generated Tentacle options> <generated image>
<generated registry login, when required> && \
podman run <generated Tentacle options> <generated image>
These are intentionally command shapes, not commands to reconstruct by hand. Use the complete block from the Realm onboarding screen so its credential, image, volume, capabilities, ports, and connection settings stay consistent. If WireGuard is configured, Cracken shows the Script and Docker Compose paths but omits standalone Docker and Podman commands because the tunnel requires the generated Compose deployment.
On macOS or Windows, prepare Podman before using a generated Podman command:
podman machine init # first time only
podman machine start
After running any deployment command, leave the onboarding screen open until the Tentacle reports Ready.
Runtime environment reference
Generated installers, Compose files, and run commands populate the runtime environment for you. This reference is for operators auditing a generated artifact or maintaining a native/manual deployment. Do not replace generated values unless you also own the deployment and understand the connection and filesystem consequences.
Tentacle process
| Variable | Required | Purpose |
|---|---|---|
TOKEN | Yes | Secret Tentacle runtime credential embedded by the generated artifact. It is distinct from the time-limited install token in the onboarding command. Never share or commit it. |
WS_URI | Yes for self-hosted deployments | Cracken WebSocket endpoint used for the Tentacle control connection. The direct binary defaults to Cracken Cloud when this is omitted. |
BACKEND_HTTP_URI | Yes for standard deployments | Cracken HTTP endpoint used to obtain filesystem access and other runtime configuration. |
TENTACLE_UPDATE_URL | No | Signed release-manifest endpoint. This is derived from BACKEND_HTTP_URI; leave both values empty to disable automatic updates. |
TENTACLE_UPDATE_INTERVAL_SEC | No | Interval between automatic update checks, in seconds. Defaults to 3600 and must be positive. |
TENTACLE_UPDATE_PATH | No | Executable replaced by an automatic update. Defaults to the current executable; generated containers use /app/cracken-worker on persistent storage. |
TENTACLE_NAME | No | Human-readable Tentacle name. Defaults to cracken-tentacle when running the binary directly. |
TENTACLE_DESCRIPTION | No | Free-form description shown with the Tentacle. |
TENTACLE_FILESYSTEM_ROOT | Yes | Root path that the Tentacle exposes through its managed filesystem. |
TENTACLE_LOCAL_SANDBOX_ROOT | Yes | Local root used for Sandbox workspaces and Vessel assets. |
ASSET_DOWNLOAD_BASE_PATH | No | Base path for downloaded assets. The direct-binary default is /app/storage; generated deployments align it with the Sandbox root. |
COVERT | Yes | Set to false for Sandbox and LOTL. Account-managed Covert artifacts set this automatically. |
BROWSER_TAKEOVER_ENABLED | Only when browser takeover is enabled | Enables browser takeover for Vessels launched by this Tentacle. |
BROWSER_TAKEOVER_PORT | Only when browser takeover is enabled | TCP port used by the browser takeover service. |
HTTP_PROXY | No | HTTP proxy hint supplied to compatible applications when proxy egress is configured. |
HTTPS_PROXY | No | HTTPS proxy hint supplied to compatible applications when proxy egress is configured. |
Keep recovery data on persistent storage
Keep ASSET_DOWNLOAD_BASE_PATH on storage that survives Tentacle process and container restarts. The Tentacle stores unacknowledged background-command responses and recovery state beneath this path. An ephemeral path can lose output and prevent a background command from recovering safely after a restart.
Generated container artifacts include a named data volume. Preserve that volume during upgrades and restarts, and verify that ASSET_DOWNLOAD_BASE_PATH resolves inside a persistent mount. If you set the path outside the generated volume, add a named-volume or bind mount at the configured path. Do not use docker compose down -v, podman volume rm, or docker volume rm while the Tentacle still has work that must recover. For a native deployment, use a persistent local filesystem and retain the directory when replacing the binary.
Automatic update trust and recovery
Generated deployments configure automatic updates. For a native or manual deployment, provide
BACKEND_HTTP_URI or an explicit TENTACLE_UPDATE_URL, keep TENTACLE_UPDATE_PATH writable and on
persistent storage, and set a positive check interval.
Tentacles accept only release manifests and binaries signed by the trust key included in the worker build. Runtime environment variables cannot replace that key. Install worker builds only from your Cracken administrator or another approved distribution source.
An available update remains Update pending while a terminal session is active, Vessel input is running, a non-Bash Vessel exists, or a Bash Vessel has live child processes. On Linux, after Bash input and child processes finish, the Tentacle closes the idle Bash Vessel and applies the update; that shell's state is not preserved. On other platforms, the operation lifecycle must close the Bash Vessel before the update can begin. Close unused sessions or finish the blocking work when an update remains pending.
While a verified update is being applied, Cracken shows the Tentacle as Updating. Wait for it to return to Ready before starting work. If Cracken shows an Update failure notice, inspect the Tentacle service logs and verify the configured update endpoint and path permissions. Retry after correcting the issue, or redeploy an approved worker build while preserving persistent Tentacle data.
TENTACLE_AUTO_UPDATE_ENABLED is a Backend-wide deployment switch and defaults to true. To pause
automatic update attempts, let any update already in progress finish when possible, then use a maintenance
window to stop Backend traffic and every Backend replica. Set the switch to false for the whole replica
set, start the replicas, and restore traffic. A rolling restart is not supported for changing this switch.
You do not need to recreate Tentacle containers or processes. While paused, new automatic updates are not
staged, idle Tentacles remain Ready, and disabled admission does not show Update failure. Repeat the
non-overlapping Backend restart with true to resume normal polling.
Before the first pause, keep the switch enabled until every Tentacle has upgraded to the current approved
worker release so it supports the Backend pause behavior. This is especially important when a worker uses
an explicit TENTACLE_UPDATE_URL. If a Tentacle does not remain Ready after a pause, restore true,
perform the non-overlapping Backend restart, update every Tentacle, and then retry the pause.
A minimal standard native environment has this shape. Obtain the runtime credential from your
account administrator; do not reuse the <install-token> from the onboarding command as TOKEN.
TOKEN=<Tentacle-runtime-credential>
WS_URI=<generated-wss-endpoint>
BACKEND_HTTP_URI=<generated-https-endpoint>
TENTACLE_NAME=<tentacle-name>
TENTACLE_FILESYSTEM_ROOT=<operator-owned-filesystem-root>
TENTACLE_LOCAL_SANDBOX_ROOT=<operator-owned-sandbox-root>
ASSET_DOWNLOAD_BASE_PATH=<operator-owned-sandbox-root>
COVERT=false
Operator-managed proxy sidecar
The standard onboarding proxy setting populates HTTP_PROXY and HTTPS_PROXY for compatible
applications. A separately managed transparent-proxy sidecar uses the variables below instead. That
sidecar is not generated by the normal Realm onboarding flow, so use these only with Cracken's
operator deployment procedure. Do not replace the generated HTTP_PROXY and HTTPS_PROXY values
with EGRESS_PROXY in an onboarding artifact: setting that variable alone does not add the sidecar
or enforce the proxy.
| Variable | Required | Purpose |
|---|---|---|
EGRESS_PROXY | Yes in sidecar proxy mode | Upstream socks5://, socks4://, http://, or https:// proxy URL. |
EGRESS_DNS | No | Comma-separated DNS servers used by the proxy sidecar. |
WireGuard deployment
The generated Compose file supplies these variables to its WireGuard deployment. Private and
preshared keys are secrets. Configure them through Advanced configuration instead of adding them
to a standalone docker run or podman run command.
| Variable | Required | Purpose |
|---|---|---|
WG_PRIVATE_KEY | Yes | Private key for the Tentacle-side WireGuard peer. |
WG_PUBLIC_KEY | Yes | Public key of the remote WireGuard peer. |
WG_ADDRESS | Yes | Tunnel address or comma-separated addresses assigned to the Tentacle-side peer. |
WG_ENDPOINT | Yes | Remote WireGuard UDP endpoint in host:port form. |
WG_ALLOWED_IPS | No for manual deployments | Destination ranges routed through the tunnel. Manual deployments default to 0.0.0.0/0; generated artifacts set this explicitly. |
WG_DNS | Yes | DNS server or comma-separated DNS servers used while the tunnel is active. |
WG_PERSISTENT_KEEPALIVE | No | Keepalive interval in seconds when required by NAT or firewall behavior. |
WG_PRESHARED_KEY | No | Optional additional preshared key for the peer. |
Choose an egress option
| Option | Use when | Behavior |
|---|---|---|
| Direct | The host's existing network path is approved for the assessment. | Tentacle traffic follows the host's route. |
| Proxy | Compatible applications should use a customer-provided HTTP or SOCKS proxy. | The generated setup supplies standard HTTP and HTTPS proxy settings to supported tools. |
| WireGuard | The assessment requires a controlled tunnel and fixed exit path. | Assessment, tool, target, and DNS traffic is tunneled through the configured WireGuard peer. |
The installation screen shows which options are available for the selected deployment method. WireGuard configuration uses the Docker Compose path. The backend WebSocket control channel remains on a direct route by design so the Tentacle can stay connected; separately approve or constrain that control path in the host and network policy.
The generated proxy option is an application hint, not a network boundary. Tools that ignore proxy settings, use raw sockets, perform direct DNS, or send UDP or QUIC traffic can still use the host's route. Use WireGuard or an operator-managed network boundary when assessment traffic must use the approved exit, and account separately for the Tentacle's backend control channel.
Why control egress
A deliberate egress path helps a security team:
- make assessment traffic attributable to an approved exit
- reach private or segmented targets from the right network
- keep customer and engagement traffic separated
- revoke or replace a route without changing the operation workflow
Network routing is still part of the engagement boundary. Confirm the approved targets, routes, and exit identity before starting active testing.
Configure Tentacle networking
- Open your realm and select Tentacles.
- Click New Tentacle and choose the sandboxed deployment method.
- Expand Advanced configuration.
- Enter either the Proxy Egress URL or the WireGuard egress settings supplied for the engagement.
- Click Apply settings to command.
- Run the newly generated command on the dedicated assessment host.
- Wait for the Tentacle to show Ready before starting an operation.
Changing advanced settings generates a replacement command with the new configuration, but it does not revoke a command copied earlier. Previous commands and their credentials remain usable until they expire or are explicitly revoked. If a command is exposed or contains an obsolete route, do not run it; ask your administrator or Cracken support to revoke the associated credential before proceeding.
Operate it safely
- Keep the Tentacle on infrastructure dedicated to authorized assessment work.
- Store generated installation credentials in a secrets manager and keep them out of logs, tickets, and operation output.
- Restrict proxy and tunnel routes to the approved engagement scope.
- Confirm the observed exit path for every required traffic type against the engagement's network plan before testing targets.
- Reconfigure or decommission the Tentacle when the engagement ends.
Get operator-level deployment guidance
Self-managed proxy enforcement and customer-specific routing are covered in the private operator guide. Contact sales@cracken.ai or your Cracken account representative for the guide and deployment support.
Next steps
- Tentacles — understand Tentacle placement, capabilities, and lifecycle.
- Vessels — review the environments a Tentacle launches.
- Deployment — choose how Cracken runs in your infrastructure.