Put your machines to work.

One command to connect a machine

Sign in to your workspace, open Machines → Add machine, and copy the private command. Run it on the server you want to add.

curl -fsSL https://hermetic.sh/install.sh | sh -s -- YOUR_TOKEN

The installer downloads and verifies a private runtime and the CLI, enrolls this machine in the selected workspace, and starts the agent. There is no resource form, second login, or browser approval. Each token connects one machine and expires after one hour; get a fresh command for the next machine.

All automatically enrolled machines share the conservative site name default. Separate hostnames do not establish independent power or network failure domains. New buckets default to two copies on two machines in one site. Existing bucket policies are unchanged.

Requirements and advanced options

You do not need to install Python or Homebrew first. The installer selects a private runtime for your operating system and architecture. Docker must be accessible to the agent user for compute. The installer starts and manages the agent automatically. See maintenance for service and container details.

For explicit resource limits, a different state directory, or a verified failure domain, see hermetic up --help. Use the same --site for machines that share power or network. Only configure independent sites when the physical infrastructure supports it.

Rename an enrolled machine with Machines → Rename in the dashboard or hermetic rename CURRENT_NAME NEW_NAME after updating the CLI. The new name applies immediately to new connections, without restarting the agent. Existing connections and stored data are preserved. Workspace admins can rename any machine; a machine credential can rename only itself.

Use hermetic login on your own computer for administrative CLI commands. Machine installation stores a machine credential, not your personal API token. Enrolled machines can mount their workspace storage without a separate login. Each receives its own storage key, which stops working when the machine is revoked. Hermetic connects enrolled network agents automatically over authenticated outbound HTTPS. No VPN client or inbound firewall port is needed. Run hermetic machines to check connectivity, hermetic connect MACHINE PORT for a TCP stream, or hermetic forward MACHINE:PORT LOCAL_PORT for a localhost-only forward. hermetic ssh USER@MACHINE COMMAND tunnels to the machine’s existing SSH server on port 22; normal SSH authentication and host-key verification still apply. Machine names (optionally ending in .hermetic) resolve inside the CLI; ambiguous names require the machine ID. Connections stay within one workspace. Workspace administrators and enrolled network machines can reach the other machines’ loopback TCP services, so enroll trusted hosts. This is a server-relayed TCP network, not a system-wide IP VPN or DNS resolver. Traffic is TLS-encrypted to Hermetic’s relay; use SSH or application TLS for end-to-end encryption. Run hermetic update on existing machines to enable networking. Agent restarts and server rollouts reconnect automatically; active TCP streams must be reopened.

Choose hardware and isolation

Machine details show physical CPU, OS, architecture, system RAM, sharing limits, and available runtimes. Choose a machine explicitly or let Hermetic find a compatible one. Work runs on the selected architecture without CPU emulation.

Native Linux sandbox

hermetic sandbox --runtime native --os linux --architecture x86_64 --memory-mb 256 --timeout-seconds 30 -- uname -a

The CLI and dashboard default to native isolation. It uses host binaries inside private Linux namespaces with enforced CPU, memory, and process limits. Home directories and host sockets are hidden; system binaries are read-only. Scratch space is temporary and counts against memory. Native execution currently has no network or bucket mounts. Bubblewrap and working systemd resource controls are required; the agent checks them before offering compute.

Native macOS isolation and microVMs are not implemented and are shown as unavailable. Docker is an optional Linux compatibility runtime; on macOS it requires a local Linux VM. Neither native Linux isolation nor Docker provides a VM boundary.

Docker compatibility

Check that your compute machine is online, then launch a container. Use the returned sandbox ID to run commands or stop it.

hermetic status
hermetic sandbox --runtime docker --image alpine:3.21 \
  --cpus 1 --memory-mb 512
hermetic exec sandbox_ID -- uname -a
hermetic stop sandbox_ID

Sandboxes have read-only roots and writable /tmp. Add --network outbound for Docker NAT networking and --workspace-mb 512 for a temporary /workspace. Scratch space uses container memory. Outbound networking permits internet and reachable LAN destinations; no host ports are published. The default is offline. Standalone sandboxes do not automatically move to another machine; use batch jobs for retries.

Run a batch across your machines

Submit a container command and a JSON array of inputs. Hermetic queues tasks, spreads them across compatible machines, and records their output. Create jobs under Sandboxes → Batch jobs or use the CLI.

{
  "image": "alpine:3.21",
  "command": ["sh", "-c", "echo $HERMETIC_INPUT"],
  "inputs": ["first", "second", "third"],
  "concurrency": 2,
  "network": "outbound",
  "memory_mb": 512,
  "workspace_mb": 128,
  "timeout_seconds": 300,
  "max_attempts": 3
}

hermetic job submit job.json
hermetic job list
hermetic job get job_ID
hermetic job wait job_ID
hermetic job cancel job_ID

Each task receives HERMETIC_INPUT as JSON, a stable HERMETIC_TASK_ID, and HERMETIC_ATTEMPT. Use your own image for web fetching, document conversion, tests, or other independent work. Up to 1,000 inputs per job; each input is at most 32 KiB. Job commands run up to their configured timeout, independently of the short interactive exec limit.

Jobs default to outbound networking and a 512 MiB temporary workspace; choose network: "none" for offline work. No machine or user credentials are injected. For object uploads, pass an explicit application credential through env; environment values are visible to workspace administrators and the host. Use explicit successful uploads to confirm durable artifacts.

Result history retains the last 64 KiB of captured output per attempt. Temporary workspace disappears when a task is removed or recreated. Choose memory and concurrency limits appropriate to your workload. Use idempotency_key on submissions to safely retry the same request.

Store encrypted objects

Create a bucket with the number of copies and independent sites your data needs. The default two-copy policy requires two storage machines. They may share the default site; independent-site replication is an optional policy for verified failure domains.

hermetic bucket project-files --copies 2 --sites 1
hermetic credentials

S3 endpoint

https://hermetic.sh/s3

Region

us-east-1

Client settings

Path-style · Signature V4

Files are split into encrypted chunks. File keys and manifests reconstruct the original bytes; storage machines do not receive decryption keys.

How copies stay protected

Writes require every requested replica to acknowledge. Placement chooses the machines with the most usable free bytes after accounting for other files, the storage reserve, quotas, and pending writes. Smaller or nearly full disks stay unused when roomier machines can satisfy your required copies and independent sites. For example, two copies can use two roomier machines; three copies on three machines still require all three. If a machine becomes unreliable, Hermetic verifies replacement copies before moving data away.

Storage priority and rebalancing

A machine whose usable limit is under a tenth of your roomiest machine’s is used only when needed: it receives replicas only if your other machines cannot satisfy a bucket’s copies and sites. You can override this per machine in its dashboard details, or with hermetic machine storage MACHINE preferred (or fallback, or auto). In the background, Hermetic moves replicas off machines used only when needed once roomier machines are online, evens out machines that are much fuller than others, and removes extra copies beyond your bucket’s policy. Each move verifies the new copy before deleting the old one, and moves are rate-limited so repairs and uploads come first.

Keep space available for writes

New replicas must fit within the usable limit shown for each machine: 80% × (free space + existing Hermetic data), or 80% of an explicit storage quota if lower. A second limit keeps at least 10% of the whole filesystem free. At 90% disk usage, Hermetic stops new allocations and prioritizes moving existing replicas to roomier machines. New allocations resume only below 85% whole-disk usage. For example, a 1 TB disk with 900 GB of other files accepts no new replicas. A replacement must be verified and the bucket’s copies and sites preserved before the old copy is deleted. Deleted replica space is returned to the filesystem automatically by updated agents. Pending writes and encrypted chunk overhead count toward the limit. If the required copies and sites cannot fit, S3 returns 503 instead of reducing replication. Reads and deletes still work, and a rejected overwrite preserves the previous file.

Free disk space or add another eligible machine to resume writes. Mounted drives may keep failed uploads in their local cache and retry; confirm that the object is visible remotely before treating it as durable.

Delete an empty bucket

Remove the bucket’s files and folders, wait for synchronization, and unmount it on your computers. Then choose Storage → Delete beside the bucket, or run hermetic bucket BUCKET --delete. Deletion refuses nonempty buckets, including buckets with empty-folder markers. There is no force-delete option. Deleting the workspace’s default bucket clears that selection; a later mount without a bucket will select or create a new default. Use an explicit bucket name to choose what you mount.

Mount a bucket at a local path

A bucket is shared storage. A mount exposes its files at a directory on one computer. Use hermetic mount BUCKET LOCAL_PATH: files from the bucket appear directly inside that path. Mount the same bucket on another computer to access the same files; the local paths can differ. A bucket name does not tie its data to a particular machine.

hermetic mount macbook-drive ~/Hermetic
# macbook-drive is the shared bucket; ~/Hermetic is this computer's local path.
hermetic unmount ~/Hermetic

Omitting the bucket, as in hermetic mount ~/Hermetic, selects the workspace’s default bucket and prints its name. hermetic mount --all-buckets ~/AllBuckets instead shows one folder per bucket. The installer includes the signed Finder integration on macOS; Linux uses FUSE and downloads its mount helper if needed. NFS is an optional access method: hermetic mount macbook-drive ~/Hermetic --backend nfs. Choosing a backend does not change the bucket’s files or replication policy.

Share files with sandboxes

On each compute machine, keep the bucket mounted and register its path with the agent. Sandbox containers get only this explicit mount, while storage credentials stay on the host.

# Keep this running in its own terminal or service:
hermetic mount project-files /mnt/project-files --allow-other --foreground

# Start the agent in another terminal:
hermetic up --site office --roles compute --cpus 4 --memory-mb 4096 \
  --bucket-mount project-files=/mnt/project-files --foreground

Stop any existing agent first. Non-root FUSE users need user_allow_other in /etc/fuse.conf. The flag allows other local users to access the mount; use a trusted machine.

hermetic sandbox --runtime docker --image alpine:3.21 --mount project-files:/data
# Optional: --node NODE_ID to pick a machine, or :ro for a read-only mount.

Mount targets can be /data, /mnt, /workspace, or subdirectories. The scheduler requires a compatible machine with that bucket mounted. Avoid concurrent writes to the same file.

Keep your machines healthy

On Linux, root installations use a system service; ordinary user installations use a user service with lingering enabled automatically so the agent survives logout. Existing service registrations are preserved. macOS uses launchd. Without a service manager, such as inside a container, Hermetic starts a tracked background agent; rerun hermetic up after restarting that container. Explicit --foreground is available for advanced supervision.

Run doctor on a machine to check credentials, storage, Docker, mounts, and the agent. It repairs private-file permissions and an inactive user service when possible. Use check mode to inspect without applying repairs.

hermetic doctor
hermetic doctor --check
# Optional: --json or --state-dir /srv/hermetic-agent

Doctor reports full disks, missing dependencies or mounts, and credentials that need attention. It leaves your data and live foreground agents in place.

Remote administration

hermetic machine exec omarchy -- uname -a
hermetic machine update omarchy

After signing in as a workspace administrator, reach any running current agent without SSH keys, inbound ports, Docker, or a compute role. The dashboard offers the same actions in machine details. Host commands run directly as the agent's OS account, outside sandbox isolation, with a 20-second timeout and 64 KiB output limit. They execute once and are not automatically retried. This is remote command execution, not an interactive terminal.

Remote updates acknowledge scheduling; check the agent version after reconnection. They require a registered service and writable CLI. Older agents need one local update first. Offline or sleeping machines remain unreachable. Machine credentials cannot administer other hosts.

Update the CLI and agent

hermetic update
# For a protected installation directory:
hermetic update --sudo

Updates verify the published checksum before replacing the CLI payload, keep the previous payload, and refresh an installed agent. The launcher and private runtime stay in place; rerun the install script to pick up runtime upgrades. Credentials, enrollment, and storage remain in place. Run as your normal agent user; --sudo elevates file installation only.

Capabilities and current limits

Hermetic is evolving. These are the boundaries to plan around today, including when you access storage through a mounted drive.