Concepts

The mental model in five minutes. Useful before you build anything serious; safe to skim if you just want to see the demo.

The three things you bring

agentry is opinionated about what you bring versus what we provide. The labels matter — they show up in the dashboard, the CLI, and every error message.

Your harness

The agentic tool you drive. Claude Code, Cursor, Roo Code, Continue.dev, or anything that speaks the Model Context Protocol (MCP).

The harness reads files, writes code, runs commands. It's the part that lives on your screen.

Your AI

The model under the harness. Claude, GPT, Gemini, open-weights models (Llama, Qwen, DeepSeek, Mistral, anything you can host or call). You configure the model in your harness — agentry doesn't pick for you.

agentry works best with long-context, agentic coding models — the frontier Claude (Sonnet, Opus), GPT, and Gemini tiers. Long context lets the AI hold whole sandboxes, configs, and logs in mind across multi-step builds; strong tool-use training is what makes the MCP loop reliable.

Want one key for every model?

Point your harness at OpenRouter. One API key, one bill, every major model — Claude, GPT, Gemini, Llama, DeepSeek, and ~200 others. Switch models with a config string change. Pay per-token at provider rates plus a tiny OpenRouter markup. This is the fastest way to A/B models without re-wiring anything.

Your server

A Linux machine running Docker. Your laptop, a Hetzner box, an EC2 instance, bare metal — anything you can SSH into.

The server is where agentry's runtime container lives. Every sandbox the AI creates, every app you ship, runs on this machine. Code and data stay on it.

What agentry provides

Three things:

1. A sandbox — an isolated environment on your server where the AI works. Each sandbox has its own filesystem, env, and processes.
2. A live URL — a sandbox or a deployed app can be reached at a public URL like my-app-3f7e2a1c.agentry.live, even though your server has no open ports.
3. A connection — the agentry bridge wires that public URL to your server through an encrypted tunnel.

That's it. agentry is the connection and the runtime. Your code, data, and apps stay on your hardware.

How the pieces flow

When you ask your harness to build something:

your harness        →   MCP call   →   agentry control plane
                                              ↓
                                  the right sandbox on your server
                                              ↓
                                      runs the work
                                              ↓
                              hands back URLs + logs + status

When a visitor opens a deploy URL:

visitor browser  →  *.agentry.live  →  the agentry bridge
                                              ↓
                                        your server
                                              ↓
                                  your app's container

No inbound port on your server. The bridge holds an outbound tunnel that your server opened; incoming HTTPS rides back over it.

Sandboxes

A sandbox is a container on your server. The AI gets:

• A filesystem rooted at /workspace
• A shell to run commands
• A package manager (npm, pip, cargo, etc.)
• Network access (your server's outbound network)
• Optional bound services (databases, AI keys, custom env)

Sandboxes have stable IDs. The harness uses one ID for the whole conversation — every tool call in that chat lands in the same sandbox. Different chats get different sandboxes by default, even if the agent picks the same descriptive name.

One sandbox, one project

A sandbox holds a single project. There's no project picker anywhere — the CLI, the harness, the dashboard, and the runtime all assume the sandbox is the project. Want a second app? Make a second sandbox.

Why name collisions don't overwrite your work

If chat A creates ecommerce-store and chat B later asks for ecommerce-store, agentry auto-suffixes the second one (ecommerce-store-7f2a). You won't lose your first project. Details in the troubleshooting guide.

Deployments, images, and your registry

This is the part most people get backwards, so it's worth getting right. There are two distinct things:

• A deployment is a live, running app. It has a stable public URL like my-app-3f7e2a1c.agentry.live, runs independently of the sandbox it came from (you can delete the sandbox and the deployment keeps serving), auto-restarts if it crashes, and streams logs to the dashboard.
• An image is a frozen snapshot of your app, built once and saved. Every time you deploy, agentry builds a fresh image and saves it to your registry. Images are the durable artifact — a deployment is just an image that happens to be running right now.

Why the split matters:

• Rollback. Every image you've ever built is kept. If a new version breaks, pick the previous image and redeploy it — same URL, back in business in seconds.
• Ship an update. When the agent changes your code, you build a new image and point the deployment at it. The URL and any custom domain stay the same.
• Move between servers. An image is portable. The same image can run on your laptop today and a Hetzner box tomorrow.

You manage running apps on the Deployments page and the saved snapshots on the Images page. Full walkthrough: Images & rollbacks.

Shipping is a human decision

You create and update deployments from the dashboard, never from the harness. Your AI builds and tests inside a sandbox; you choose when something goes live. (agentry deploy doesn't exist on purpose.)

Your registry

To keep your images, agentry needs somewhere to put them — a container registry you own (GitHub Container Registry or Docker Hub). You connect it once in the dashboard. It's a private store: your images are pushed there, never to anything public. Without a registry a deploy still runs, but you lose rollback and cross-server moves. See Connect a registry.

Authentication

Want only logged-in users to reach your app? agentry can put a login screen in front of any deployment — email + password out of the box, plus social login (Google, GitHub, Microsoft, Apple, or any OpenID Connect provider). You wire it up with agentry auth; no auth code in your app required. See Authentication.

Bring your own model

This is structural to how agentry works, not just a billing preference.

• You configure your AI in your harness, not in agentry.
• You pay your model provider directly at their rate. agentry doesn't sell tokens.
• You can switch models any time without redoing your setup.

Why this matters:

• Prototype on a cheap or free-tier model. Switch to a frontier model for the demo. No re-wiring.
• Use open weights when you want full control. agentry never sees the bytes.
• Aggregate every provider behind one key with OpenRouter and flip models with a single config line.
• Your AI bill goes to one place: your provider. No agentry markup, no monthly cap.

The trade-off: you get the bill. agentry can't make Anthropic or OpenAI cheaper. But the marginal cost of iterating is whatever your provider charges, no resold-tokens premium.

Servers

A server is the machine that runs your sandboxes and apps. (You'll occasionally see the word cluster in the CLI and API — it's an older alias for the same thing; the commands accept either.)

You can have multiple servers — a laptop for prototyping, a Hetzner box for production. Sandboxes and deployments belong to one server. Pick the active one in the dashboard, or with:

agentry server use <name>

Bindings

A binding is a service (database, AI provider, API) that you wire into your server once, and every sandbox on that server inherits it.

Example: bind MongoDB to your server. Every new sandbox automatically gets a MONGODB_URL environment variable. The AI's code reads it; everything just works. Skip it if you don't need it.

Bindings live at the server level so you don't have to repeat yourself in every project. Full detail: How bindings work.

What agentry never sees

Worth being explicit about. agentry does not have visibility into:

• The source code your AI writes (it's on your server)
• The data your apps store (on your server)
• The conversations between you and your AI (those run inside your harness, not through us)
• Your model API key (you set it in your harness)

agentry does route your app's public HTTPS traffic across our edge. TLS terminates at the bridge (which presents the *.agentry.live certificate) and is re-encrypted into the tunnel to your server — so visitor traffic passes through our edge in flight, but we don't store it.

More detail in the security model.

Pricing

agentry is free, forever. There's no metered tier, no token markup, no trial.

You pay your model provider for tokens. You pay your server provider for the box (or use your own laptop, which is free).

Next

• Security model — what's encrypted, what's isolated, what we can and can't see.
• Wire up your harness — start with whichever harness you use.
• Ship an app — take a sandbox to a live URL.