hatcher

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 9 Open GitHub ↗

Deploy your local agent to any remote sandbox. Claude Code - Hermes agent - Cloudflare Sandbox - Daytona - more to come

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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:

```bash
$> 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:
```bash
$> 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`

```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:

```text
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:

```text
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

Read [CONTRIBUTING.md](CONTRIBUTING.md).

## Roadmap

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

## Documentation

- [README.md](README.md): documentation for users.
- [CONTRIBUTING.md](CONTRIBUTING.md): documentation for contributors.
- [AGENTS.md](AGENTS.md): documentation for agents.

## License

MIT -- see [LICENSE](LICENSE).

hatcher

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README