convez.ai
AgenteDevOps & InfraestruturaAvançado
ebourmalo

Hatcher - Deploy de Agents para Sandbox Remoto

ebourmalo/hatcher

Leve seu agent local para a nuvem com um comando, execute 24/7 sem parar sua máquina

Ver no GitHub
BomPluginScore · de 0 a 100

Ferramenta CLI que empacota e faz deploy de agents locais (Claude Code, Hermes) para provedores de sandbox (Cloudflare, Daytona), transformando-os em managed agents que rodam 24/7 na nuvem. Usa um arquivo declarativo `hatcher.json` como fonte única de verdade e oferece acesso remoto por terminal para interação contínua.

Instalação

$npx convez-ai ebourmalo/hatcher

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
11
Forks
1
Acompanhando
0
Saúde
57%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Deploy de agents Claude Code ou Hermes para execução contínua em produção
  • Gerenciamento de múltiplos agents em sandbox providers diferentes com configuração única
  • Automação de fluxos de trabalho que requerem execução persistente na nuvem

Veredito

Ferramenta madura e bem arquitetada para operacionalizar agents em produção, reduzindo fricção entre desenvolvimento local e deployment remoto. Suporte inicial a Cloudflare e roadmap claro para múltiplos runtimes e provedores.

README

A tradução para o português deste README ainda está na fila.

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 / SandboxDaytonaCloudflare
Claude Code (claude-code)WIPSupported
Hermes (hermes)WIPSupported

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

Read CONTRIBUTING.md.

Roadmap

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

Documentation

License

MIT -- see LICENSE.

Ver o original no GitHub

Bom para

Relacionados