Set Up sandboxed.sh and Remote Access with Localtonet

Version, evidence, and tutorial scope

Reproducible deployment instructions need a named source revision. This tutorial targets the sandboxed.sh v0.12.0 release, identified by the project as commit 33c0345. That release added first-class Grok support, transcript streaming changes, new mission lifecycle states, dashboard API-base inference improvements, and related web and iOS changes. The repository reports substantial development on master after this release, so commands, environment fields, API routes, and interface labels from the current branch must not be silently treated as part of v0.12.0.

The supplied evidence confirms that the repository contains Dockerfile, docker-compose.yml, .env.example, INSTALL.md, backend source, and dashboard source. It also confirms that the public setup documentation installs the backend on a server while presenting the dashboard as a separate choice: a Vercel-hosted Next.js dashboard, a local dashboard started with Bun, an iOS application, or another compatible control surface.

This limitation also means there is no responsible basis for calling Docker the universally recommended installation method. The current project offers an installation comparison and links to both Docker and native installation guides. This tutorial deliberately chooses Docker Compose because the repository includes that deployment definition and because Compose provides a consistent set of inspection and lifecycle commands. It does not claim that Docker is best for every host.

You can review the selected release in the sandboxed.sh v0.12.0 release and the evolving project in the official sandboxed.sh repository. Do not combine files copied from master with a v0.12.0 deployment unless you have reviewed and tested the differences.

Understand the backend, control plane, and user interfaces

sandboxed.sh is a self-hosted mission-execution backend. It does not provide the model that reasons about a task. Instead, it prepares isolated workspaces, starts and monitors supported agent runtimes, synchronizes configuration, and turns runtime output into structured events for its clients. The selected runtime, such as Claude Code, OpenCode, Codex, Gemini, or Grok, performs the underlying agent work and has its own installation and provider-authentication requirements.

The project describes a two-part system. A coordinator decides what should happen and when, then drives sandboxed.sh over MCP. Hermes is the project's reference coordinator, but the architecture permits another MCP-capable assistant. sandboxed.sh receives executable units of work and runs them in workspace-aware environments. Structured results return through server-sent events, webhooks, or the applicable client connection.

The current control-plane model

Current project material describes the canonical agent-native control plane as portfolio → project → track → attempt → action → receipt → evidence. This model is broader than an older description based only on projects, controllers, conversations, and missions. The latter terms remain useful runtime concepts, but they are not the complete canonical model.

A project can have an active, blocked, or paused mode and an autonomy grant covering concerns such as merge authority, budget, and parallelism. Project state is stored on the sandboxed.sh host and is served through project API routes. A controller can wake on a schedule, read the control conversation and project state, and dispatch a mission when real filesystem, Git, build, test, or pull-request work is required.

Prepare a host for the pinned Docker deployment

Use a host under your administrative control. It needs Git, Docker Engine, and the Docker Compose plugin. The account performing deployment must be able to communicate with the Docker daemon. It also needs enough storage for images, application state, repositories, workspace copies, runtime configuration, build artifacts, and logs.

Resource requirements depend on workload. A small source review and a parallel build have very different CPU, memory, and disk profiles. The project evidence does not define a universal minimum specification, so size the host around the runtime, repositories, build systems, and mission concurrency you intend to permit.

Run prerequisite checks

git --version
docker version
docker compose version
docker info

Each command must succeed before continuing. A Docker permission error is a host-administration issue, not a sandboxed.sh problem. Resolve it according to your operating system's supported Docker installation method rather than running an unreviewed command with elevated privileges.

Prepare runtime and network access

• Choose at least one supported runtime to test first.
• Prepare its provider account, local model access, API credential, or provider login as required by that runtime.
• Allow only the outbound network destinations needed to obtain source, images, dependencies, provider responses, and Localtonet connectivity.
• Use a disposable repository or directory for the first mission.
• Decide where persistent backend state, Library data, and workspaces will be stored.
• Keep the backend and dashboard private until authentication and authorization have been verified.

Install sandboxed.sh v0.12.0 with Docker Compose

The following procedure checks out the exact release used by this tutorial and uses its included Compose definition. It deliberately validates configuration before starting containers. It does not substitute invented environment values for the checked-out release.

git clone https://github.com/Th0rgal/sandboxed.sh.git
cd sandboxed.sh

git fetch --tags
git checkout v0.12.0
git rev-parse --short HEAD

cp .env.example .env
chmod 600 .env

docker compose config
docker compose up -d --build
docker compose ps
docker compose logs --tail=200

The revision check should report 33c0345. If it does not, stop and inspect the tag resolution before supplying credentials or starting containers.

Complete the environment file safely

Open .env.example and docker-compose.yml from the checked-out tag side by side. Preserve documented non-secret defaults unless your deployment requires a deliberate change. For every blank or placeholder field, determine whether it controls a backend bind address, public backend URL, state path, workspace path, provider integration, runtime executable, database, or credential.

The supplied evidence does not contain the actual field list for this release, so this article cannot truthfully enumerate it. Do not guess names based on another project or a newer master checkout. A field is required when the tagged configuration or docker compose config identifies it as required, or when the tagged installation guide says the related feature cannot start without it.

• Do not commit .env.
• Do not place provider tokens in Compose labels, public URLs, screenshots, or support messages.
• Do not paste the Localtonet device token into sandboxed.sh configuration.
• Restrict access to environment and credential files.
• Use separate credentials for testing and production.
• Rotate any secret accidentally recorded in shell history, logs, or source control.

Discover the verified backend binding

Do not assume port 3000. Inspect the fully resolved Compose configuration and the running container mappings:

docker compose config
docker compose ps
docker compose port SERVICE CONTAINER_PORT

Replace SERVICE and CONTAINER_PORT only after reading their actual values from docker compose config. The final command is a Docker Compose inspection pattern, not a claim about a particular sandboxed.sh service name or port.

Connect a dashboard without confusing it with the backend

The sandboxed.sh public documentation explicitly separates backend installation from dashboard hosting. The backend runs on the server. A dashboard or application connects to that backend through its configured server URL. As a result, successfully opening a Next.js development page does not prove that the sandboxed.sh backend is healthy, and tunneling that development page does not necessarily expose the backend used by remote clients.

Local Bun dashboard

The documented local dashboard entry point is the dashboard directory and the startup command is:

cd dashboard
bun dev

Bun must already be installed, and dependencies must have been prepared according to the package metadata in the selected revision. The supplied evidence does not identify a version-specific dependency-install command, API-base variable, or development-server port, so those values cannot be added safely here. Use the URL printed by bun dev, then verify through browser network tools that the page is contacting the intended backend rather than a stale or inferred address.

Release v0.12.0 mentions local dashboard API-base inference. Inference is convenient, but it is not a substitute for verification. Inspect API requests and confirm their destination before publishing either service.

Verify the backend and dashboard locally

Verification should move through layers. First check Docker. Then test the backend directly. Next verify the dashboard-to-backend API path. Finally, test the event stream and one low-risk runtime. This order keeps application, runtime, and tunnel failures separate.

Check container state and health

docker compose ps
docker compose logs --tail=200
docker compose top

Required containers should remain running instead of repeatedly restarting. If the Compose file defines health checks, inspect their state in docker compose ps. A container without a declared health check can be running while its application is still unusable, so continue with an HTTP test.

Test the observed backend endpoint

Substitute the host and port reported by the pinned Compose deployment:

curl -i http://BACKEND_HOST:BACKEND_PORT/

An HTTP response proves that a process is reachable at that route. A 404 may still prove network reachability if the backend does not serve its root path, but it does not prove API health. The supplied evidence identifies project routes under /api/projects/* on current project material, but it does not establish an unauthenticated health route for v0.12.0. Do not invent one. Use a route shown by the tagged application or by the dashboard's observed requests.

Verify the dashboard API path

• Open the dashboard URL printed by its host or development server.
• Confirm that HTML, scripts, fonts, and other static assets load.
• Open the browser network panel and identify API requests.
• Confirm that those requests target the intended backend origin.
• Check for authorization failures, blocked cross-origin requests, mixed-content errors, and repeated retries.
• Open a mission or project view and confirm that data comes from the selected backend.

Verify event streaming

sandboxed.sh sends structured mission progress to its clients. Current project material describes SSE and webhook delivery, while release v0.12.0 specifically changed transcript and trace handling. Keep a browser network panel open while viewing a test mission. The streaming request should remain connected as appropriate, and new mission events should appear without repeatedly reloading the page.

Run a low-risk first mission

The current execution contract documents a stable mission sequence: the user creates a mission with a workspace and agent backend, sandboxed.sh prepares a per-mission directory, synchronizes Library content, writes runtime-specific configuration, launches the harness through the workspace execution layer, and converts the harness's JSON output into a unified event stream.

Exact interface labels vary between release v0.12.0, later web revisions, iOS, and other control surfaces. The evidence does not expose a complete screenshot-by-screenshot form definition for the selected release, so the walkthrough below identifies the required documented controls without inventing button names.

Runtime-generated workspace files

The project documents runtime-specific files generated from Library content, backend settings, and workspace settings. OpenCode uses configuration at the workspace root and under .opencode. Claude Code uses settings and skills under .claude plus a workspace CLAUDE.md. Codex uses configuration and skills under .codex. Gemini and Grok use their native CLI backends and provider-specific authentication.

Treat these as generated operational files. If a mission receives the wrong tools or instructions, compare the Library, backend settings, and workspace settings before manually editing generated mission output.

Host and container workspace behavior

A host workspace runs the harness directly on the host with the mission directory as its working directory. A container workspace runs through the project's container-aware execution layer. Built-in shell and file operations occur in that selected context.

Host facilities are not automatically available inside a container workspace. The project specifically notes that the host X11 socket is not bind-mounted for normal container harness or MCP execution. Desktop automation therefore requires an explicitly supported display configuration or a suitable host workspace. Do not expose the host desktop or add broad mounts simply to make an initial test pass.

Operate, back up, update, and roll back the deployment

Compose provides concrete commands for routine container operations, but durable state depends on the volumes and bind mounts declared by the selected release. Inspect those mappings before backing up, removing, or replacing anything.

Status, logs, restart, and stop

docker compose ps
docker compose logs --tail=200
docker compose logs -f
docker compose restart
docker compose stop
docker compose start
docker compose down

docker compose stop stops containers while retaining them. docker compose start starts those stopped containers. docker compose restart restarts services. docker compose down removes the Compose containers and network but, without a volume-removal option, normally leaves named volumes in place. Verify the release's bind mounts and external resources before relying on that behavior as a backup strategy.

Inspect persistence

docker compose config
docker compose ps -q
docker volume ls

In the rendered Compose configuration, identify named volumes and host bind mounts used for project state, workspace data, Library content, configuration, runtime credentials, and databases. Not every item needs the same backup treatment. Container images and generated caches can usually be recreated, while project records, unique workspaces, Library changes, and irreplaceable credentials need deliberate handling.

Back up the deployment

Stop mission creation and wait for active work to finish. Record the deployed commit, save the Compose and non-secret configuration files, and back up each identified persistent path with the storage platform's supported method. Back up the Library repository through Git as well as through storage snapshots when it contains unpushed changes.

Do not copy a live database file without confirming that its storage engine supports that method. The current architecture identifies projects.db on the backend host, but the supplied evidence does not define a release-specific online backup command. A maintenance-window filesystem snapshot or an application-supported export is safer than assuming a live file copy is consistent.

Update to a reviewed revision

git fetch --tags
git status
git checkout NEW_REVIEWED_TAG
docker compose config
docker compose build
docker compose up -d
docker compose ps
docker compose logs --tail=200

Replace NEW_REVIEWED_TAG with a release you have actually reviewed. Before starting it, compare .env.example, docker-compose.yml, storage mappings, migration notes, authentication behavior, API changes, and dashboard compatibility with the previous revision. Repeat the direct backend test, dashboard test, event-stream check, and disposable mission after updating.

Roll back safely

A source rollback does not necessarily reverse a database or storage migration. Preserve the old source revision, image identifiers where practical, configuration, and a pre-update backup. If validation fails, stop the new services, restore storage only according to the project's migration guidance, check out the previous tag, validate its Compose configuration, and start it again.

docker compose down
git checkout v0.12.0
docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=200

These commands restore the selected source and Compose definition. They do not automatically undo data-format changes. If an update migrated durable data incompatibly, restore the verified pre-update backup before restarting the older release.

Publish the verified service with a Localtonet HTTP tunnel

Decide what remote users actually need. An iOS app, separately hosted web dashboard, CLI, or coordinator normally needs access to the sandboxed.sh backend. A remote browser may instead need access to a locally hosted dashboard, but that dashboard must still have a valid path to its backend. These are different targets and may require different exposure decisions.

Our client establishes an outbound connection to a Localtonet relay server. The HTTP tunnel provides a public HTTPS URL without requiring inbound router port forwarding, firewall changes, VPN setup, or a public IP address. The tunnel is available only while the selected client device is connected and the tunnel is running.

See the Localtonet HTTP tunnel documentation for the current dashboard workflow. Available protocols, process types, regions, and options can vary by current product configuration or plan, so select values shown in your account rather than copying unavailable settings.

Choose the correct Localtonet target

Test streaming through the tunnel

A normal page load does not prove that mission streaming works. Open a low-risk mission through the public URL and watch the browser network panel. Compare it with the same mission locally. If local streaming succeeds but remote streaming fails, record the request URL, HTTP status, browser origin error, disconnect timing, and sandboxed.sh logs.

Do not add speculative WebSocket, buffering, header, or origin settings. The current evidence describes SSE for project and mission integration and structured event streaming, but a specific route and proxy adjustment must be based on the selected release and the observed failure. Localtonet should target the HTTP service that already handles the working local stream.

Apply least privilege to the complete deployment

Remote connectivity is only one security layer. The sandboxed.sh backend can coordinate tools with meaningful filesystem, source-control, provider, and network privileges. Protect the application endpoint, host, runtime credentials, repository credentials, workspace boundaries, and Localtonet device token independently.

• Require verified application authentication and authorization before public exposure.
• Use repository credentials limited to the repositories and actions required.
• Keep test, development, and production credentials separate.
• Limit provider credentials using provider-supported controls.
• Review project mode, autonomy grant, merge authority, budget, and parallelism.
• Use narrow bind mounts and avoid exposing unrelated host directories.
• Restrict access to .env, runtime login caches, databases, and backup files.
• Do not place secrets in prompts, mission objectives, event output, public URLs, or screenshots.
• Review logs and mission evidence for accidental credential disclosure.
• Stop the Localtonet tunnel when remote access is not needed.

Test authorization with a separate signed-out browser or device. Verify denial of project data, transcripts, traces, workspace files, configuration changes, and mission controls. HTTPS protects traffic to the public tunnel address, but it does not decide who is allowed to operate the application.

Troubleshoot each layer in order

Compose cannot render the configuration

Run docker compose config and address the first reported error. Check for unset variables, malformed interpolation, missing mounted files, duplicate ports, and paths that do not exist. Confirm that the checkout is still v0.12.0 and that the local .env was created from that tag's example rather than from master.

A container exits or repeatedly restarts

docker compose ps
docker compose logs --tail=300
docker compose logs SERVICE

Replace SERVICE with the actual Compose service name. Investigate the first meaningful application error. Typical categories include incomplete configuration, storage permissions, unavailable dependencies, failed runtime discovery, or an occupied host port. Do not repeatedly restart a container without correcting its startup failure.

The backend does not answer locally

Confirm the published mapping with docker compose ps and the resolved model with docker compose config. Test the observed address with curl. A refusal means no process is accepting the connection at that address. A timeout points toward binding or network filtering. An HTTP response shifts investigation from the network path to the route, authentication, or application.

The dashboard loads but remains empty

Open browser developer tools and inspect the destination and status of API requests. Verify that the API base points to the intended backend, not the dashboard's own development port. Check for authorization errors, cross-origin failures, mixed-content blocking, and stale configuration. Compare the same backend route with a direct local request.

No agent runtime can start

Separate backend health from runtime health. Check whether the runtime executable or service is available in the selected workspace context, whether provider authentication is valid, and whether credentials are made available through the supported configuration. A runtime installed on the host is not automatically available inside a container workspace.

A mission cannot access expected files

Verify the selected workspace type and mission directory. Inspect the Library, backend settings, and workspace settings that generated the runtime configuration. Do not solve the problem by mounting the entire host filesystem. Make the smallest justified path available or move the disposable repository into the intended workspace.

The dashboard stops updating during a mission

Check local streaming first. Inspect backend logs, runtime output, CPU, memory, disk space, and container activity. Mission workloads can be bursty, and resource contention can starve an API or event stream. If the event stream is already broken locally, changing Localtonet settings will not repair it.

The local service works but the public URL does not

• Confirm that the Localtonet client is running and connected.
• Confirm that the selected AuthToken belongs to that device.
• Confirm that the tunnel was started after creation.
• Test the target IP address and port from the client device.
• Replace localhost if the client and service run on different devices.
• Confirm that the selected relay remains available.
• Check that the target is the intended backend or dashboard, not an assumed port.
• Retry the assigned public HTTPS URL from another network.

The page works remotely but streaming fails

Compare browser network traces for local and public sessions. Confirm whether the stream reaches the same backend route, whether authentication is sent, and whether the failure is an HTTP response, origin restriction, disconnect, or application error. Correlate the request with sandboxed.sh logs. Make only a correction supported by the observed error and the selected release.

Frequently asked questions