Concepts
Every primitive in Gentity Compute maps to something concrete on the underlying infrastructure. This page is a glossary plus a quick mental model so you can predict what a given command does.
Agent
An agent is a template — a Docker image plus a default memory / CPU / volume size plus a recipe for how Gentity should run it and which models it accepts.
Today the catalog ships five: openclaw, hermes, aider, claude-code, and browser-use. List them at runtime with gentity agents or browse the per-agent guides.
Instance
An instance is one running copy of an agent. It is backed by:
- A Fly Machine — an isolated Firecracker microVM with its own filesystem and network namespace.
- A Fly Volume — encrypted persistent storage attached at the agent's data path (e.g.
/opt/datafor Hermes,/workspacefor Claude Code). - A unique subdomain with an automatically-issued TLS certificate.
Each instance has an id (cmp...) and a subdomain (he-er9eqtnh, cl-x7k2m9, etc.). CLI commands accept either, or any unambiguous prefix.
Subdomain
Every instance gets a unique URL of the shape <subdomain>.gentity.ai. The subdomain prefix is derived from the agent (cl-, he-, op-, etc.) followed by a random 8-char tail.
Treat the subdomain like a secret.There is no per-request auth between Gentity's edge and the agent process inside — the URL is the credential. Anyone with cl-x7k2m9.gentity.aican use that agent until you stop or delete it. Don't paste subdomains into public chat or commit them to repos.
Volume
Each instance gets its own persistent volume sized at the agent's default (5GB for Aider/Claude Code, 10GB for Hermes/OpenClaw/browser-use). State written to the volume survives stop → start; only delete destroys the volume.
Volumes are pinned to the region they were created in — they don't migrate. Today everything defaults to iad (US East). Pass --region to compute create if you need a different one (see the CLI reference for the supported list).
Model provider
When you create an instance you pick a model (e.g. claude-sonnet-4-5) and provide an API keyfor the provider that hosts it. Gentity injects the key into the container's environment as the right env var (ANTHROPIC_API_KEY, OPENAI_API_KEY,OPENROUTER_API_KEY, etc.) — the agent calls the LLM directly from inside its microVM.
Implications:
- You pay the model provider directly.Gentity doesn't proxy your model calls and doesn't markup tokens.
- Your prompts never touch Gentity. They go straight from the agent in your microVM to Anthropic / OpenAI / etc.
- Keys are encrypted at rest. AES-256-GCM, decrypted only when injecting into a new instance.
Token (API)
A token is what the CLI / REST API use to authenticate as you. Mint one at /dashboard/settings/tokens. Tokens look like gn_live_<52 chars>. We store only a sha256 hash, so a leaked token can be revoked but the plaintext is never recoverable from our database.
Tokens scope to the entire user — they can do anything you can do on the dashboard. Mint a separate token per machine / CI runner so you can revoke selectively.
Lifecycle
| State | Compute billed? | Volume billed? | Reachable? |
|---|---|---|---|
creating | From the moment the Machine boots | From volume create | Not yet |
running | Yes | Yes | Yes |
stopped | No | Yes (cheaper) | No (HTTP returns 502) |
error | Like the underlying state | Yes | Depends |
Isolation model
Two agents owned by the same user are still fully isolated at the kernel level — they each run in their own Firecracker microVM with their own filesystem, their own process tree, and their own NIC. A runaway loop in one agent cannot exhaust resources in another.
Cross-instance communication is plain HTTPS over each instance's subdomain. There is no shared in-cluster network today; if agent A wants to call agent B, A makes an outbound HTTPS request to https://<B-subdomain>.gentity.ai/ like any other external service.