Hatcher - Deploy your local agent to any remote sandbox

Hatcher is a CLI tool that packages and deploys your local agent (e.g. Claude Code, Hermes agent) to a sandbox provider (e.g. Cloudflare Sandbox, Daytona). Your local agent becomes a managed agent running 24/7. You can safely close your mac now.

It uses a single declarative file hatcher.json as the source of truth for the deployment, packages your agent into a .hatcher folder, builds a docker container and deploys to a sandbox provider with a remote terminal access. Interact with your agent the same way you did before, except now it runs securely in the cloud.

Hatcher is not an agent runtime, it's a deployment tool.

Agent runtime / Sandbox	Daytona	Cloudflare
Claude Code (claude-code)	WIP	Supported
Hermes (hermes)	WIP	Supported

TL;DR

• CLI (Ink-based TUI) to create, deploy and connect to your managed agent.
• 1 Hatcherfile hatcher.json to define your agent, its harness, its sandbox
• 1 deployment = 1 managed agent = 1 sandbox = 1 tmux session.
• Docker-based sandboxes: easy to package, test and deploy.
• Env vars and secrets are injected on the fly during deployment.
• Transparent: shows all external commands before execution.
• Remote terminal access for a seamless interactive TUI. Stable and secure.
• Extendable: designed to safely add agent runtimes and sandbox providers.
• Battle tested tool for CLI commands, TUI, operations, docker images and deployments

Quick Start

Prerequisites:

• Node.js 24+.
• Docker for image builds (and optionally local image validation).
• An agent already installed and running locally.

Deploy your first agent:

$> npm install -g hatcher    # install hatcher
$> hatcher init              # create your hatcher file (hatcher.json)
$> hatcher deploy            # deploy your agent
$> hatcher connect           # connect to your agent via a remote PTY

Optional: before deploying, you can check / debug / validate your sandboxed agent locally:

$> hatcher test image

CLI Usage

• hatcher init Interactive wizard that detects your local runtime, lets you choose a sandbox provider, and writes hatcher.json.
• hatcher deploy Syncs local runtime state, resolves env vars, regenerates .hatcher/, asks for confirmation, then deploys.
• hatcher status Shows the current deployment/session state for this agent.
• hatcher test image Builds the generated Docker image locally and runs a non-network readiness smoke test inside it. This is optional and does not deploy.
• hatcher connect Connects to the current remote session using the provider-specific access path.
• hatcher destroy Tears down the current deployed session.

Global flags:

• --verbose Streams external command output in the CLI.
• --debug Enables debug-only deploy/connect paths where available. Also use a debug docker file if available

Example of a Hatcher file hatcher.json

{
  "identity": {
    "name": "my-agent",
    "file": "SOUL.md"
  },
  "agent": {
    "runtime": "hermes",
    "model": "zai/glm-5.1",
    "skills": ["github/github-pr-workflow"]
  },
  "deployment": {
    "provider": "cloudflare",
    "env": ["GLM_API_KEY"]
  }
}

The schema is available in src/schema/hatcher.ts.

How Hatcher Works

1. Load and validate the hatcher file hatcher.json.
2. Detect local agent runtime state.
3. Resolve env vars listed in deployment.env.
4. Packages all agent files into a deployment folder .hatcher/.
5. Generate provider artifacts, build the Docker image, and deploy through the selected sandbox provider.
6. Save deployment/session state.
7. Connect through the provider-specific remote access path.

Runtime files flow through one staging model:

agent source files -> .hatcher/ staging -> Docker image runtime paths

Generated files:

• .hatcher/ is generated deployment output.
• .hatcher/state.json stores the current deployment/session state.
• .hatcher/.env stores local deployment secrets such as REMOTE_SHELL_AUTH_TOKEN.
• .hatcher/{any_sandbox_specific_file}
• Auto-generated files should never be edited directly.

You should never edit any file in the folder .hatcher.

Security

deployment.env in the Hatcher file is the single source of truth for the env vars injected in the sandbox.

Hatcher resolves each listed env var from:

• the runtime .env file when the agent runtime has one, for example ~/.hermes/.env;
• the current shell environment.

Secret values are never written to hatcher.json or printed anywhere. Secret values to manage the sandbox are stored in .hatcher/.env; keep this file ignored and never commit it.

For Cloudflare remote shell access, Hatcher generates REMOTE_SHELL_AUTH_TOKEN during deploy, stores it in .hatcher/.env, and sends it to Cloudflare as a secret. Cloudflare debug endpoints are generated only when deploying with hatcher deploy --debug.

Session Management

Hatcher keeps one current remote session per managed agent:

1 Hatcher file = 1 managed agent = 1 sandbox = 1 tmux session

.hatcher/state.json stores the current deployment/session state. hatcher connect uses that state to reconnect through the selected provider.

Cloudflare deployments update in place. Daytona support is experimental / WIP and uses a replace-style lifecycle.

Remote terminal access

You will have the exact same experience / TUI between your local agent and your managed agent (deployed). The remote access offers a PTY either natively by the sandbox provider CLI or via WebSocket (CloudFlare).

Support / Issues

When opening an issue, include:

• agent runtime;
• sandbox provider;
• command you ran;
• relevant logs;
• useful .hatcher/state.json context.

You can always use flags --verbose and --debug to collect a maximum amount of logs.

How to Contribute / add an agent runtime / add a sandbox provider

Read CONTRIBUTING.md.

Supported provider ids are cloudflare and daytona. To add an agent runtime, add its id to AgentRuntimeSchema and follow the runtime contract failures. To add a sandbox provider, add its id to EnvironmentProviderSchema and follow the provider contract failures.

Roadmap

• Extend Hatcher with more agents and sandboxes.
• Add a terminal browser access.
• Add A2A
• Manage multi sessions

Documentation

• README.md: documentation for users.
• CONTRIBUTING.md: documentation for contributors.
• AGENTS.md: documentation for agents.

License

MIT -- see LICENSE.