The docs are prose
Written to be read by a person over coffee, not parsed into steps. An agent has to guess at the shape of things and often guesses wrong.
For agents
Your agent can write it.
It just can't ship it.
Every coding agent hits the same wall. It writes a working app in an afternoon, then needs a server, a domain, a certificate, a database and a login — none of which it can conjure, and all of which are on you. Astrodock is the other half: a deploy target built to be driven by something that isn't a person.
Why this is hard today
Deploy targets assume
a human is watching.
The feedback is a dashboard
The deploy "worked" if a badge turns green somewhere. An agent can't see a badge, so it can't tell success from silence.
The credentials are all-or-nothing
Giving an agent the key to deploy usually means giving it the key to everything, including your users.
1 · The contract
A file written for
the thing reading it.
Astrodock ships AGENTS.md: not a tutorial, a specification. The layout a
deployable app must have, the rules its server must follow, the manifest schema, the
full list of variables it will be handed, and the commands that drive a deploy.
Point Claude Code or Cursor at it and it has everything. There is no step where somebody has to translate the docs into instructions.
### Hard rules for the server 1. Bind ASTRODOCK_PORT 2. Namespace every route under /api 3. Add GET /health → 200 4. Read config from injected env. Never hardcode. Never commit secrets. ## 7. Definition of done apply && deploy:watch ends in success, the URL serves the app, and a granted user can log in.
{
"slug": "oncall",
"subdomain": "oncall",
"runtime": { "type": "node" },
"auth": { "mode": "platform" },
"database": { "mode": "internal" },
"storage": { "mode": "none" },
"env": [
{ "key": "SLACK_WEBHOOK",
"secret": true, "required": true }
]
}
2 · The manifest
One file that says
what the app needs.
The agent writes an app.json declaring what the app is and what it
wants: a database, storage, sign-in, and the names of any secrets. Astrodock reads it
and provisions accordingly.
Note what isn't in there — values. The manifest names a secret; it never carries one. An agent can commit this file to a public repository without thinking about it.
It's schema-validated, so a malformed manifest fails immediately with a specific error rather than half-deploying something strange.
3 · The environment
Everything handed over, nothing guessed.
At deploy the app receives a documented set of variables. The agent doesn't have to invent connection strings or work out its own URL — it reads them.
Where it is
ASTRODOCK_APP_URL and the port to bind. The app can build its own
callback URLs without being told what domain it lives on.
What it can use
A database connection string and storage credentials, present only if the manifest asked for them.
How to authenticate people
The address to send a browser to, the internal address for exchanging the code, and the app's own identifiers.
4 · The loop
A deploy that reaches a verdict.
This is the part most platforms get wrong for agents. A deploy that returns "queued"
is useless to something that has to decide what to do next. deploy:watch
streams the build and exits on success or failure — so the agent knows, and can fix
and retry without a person in the loop.
$ astrodock apply Created "oncall" · internal database ready · Caddy reconfigured $ astrodock deploy:watch Deploy blocked — set these first: - SLACK_WEBHOOK (required app variable has no value) $ astrodock set-secret SLACK_WEBHOOK Set SLACK_WEBHOOK for "oncall". $ astrodock deploy:watch Installing… building… publishing… ✓ deploy success
Failures are specific
"Deploy blocked — SLACK_WEBHOOK has no value" is something an agent can act on. "Something went wrong" is not.
Logs are readable after the fact
Every build is kept with its full output, so an agent — or you — can diagnose a failure that happened while nobody was looking.
5 · The key
Hand over the deploys,
not the platform.
An agent gets its own scoped API key. It can create apps, set secrets, trigger deploys and read logs. It cannot read your users, change their access, or mint more keys — those need an administrator, and a key isn't one.
That boundary is enforced by the platform, not by the agent's good behaviour. If something goes wrong at 2am while it's working unattended, the blast radius is the apps it was given, and nothing else.
The full agent guide →Getting started
What you actually type.
Point your agent at the platform, give it the key, and describe the thing you wanted. The contract does the rest.
Read AGENTS.md at docs.astrodock.ai. Build a tool that tracks who's on call, with sign-in, and deploy it to my platform. The key is in ASTRODOCK_TOKEN.