# Automaton

Automaton is a self-hosted platform for building, deploying and publishing web apps. The user runs their own server (Studio, API, app store) and one or more Runners that run the apps. Documentation: https://automaton.monster/docs/ . This file is the index for AI agents; every page below is one task with exact commands and a check after each step.

## Start here

Every page below is one task with exact commands and a check after each step. Follow them in order and do not skip the checks.

**Installing a server for the user.** Pages, in order: [Install the server](https://automaton.monster/docs/install-server) (section "For AI agents"), [Create the first administrator](https://automaton.monster/docs/first-admin), [Install and authenticate the CLI](https://automaton.monster/docs/automaton-cli), [Add a Runner](https://automaton.monster/docs/deploy-runner). Overview for the user: [Install with your AI agent](https://automaton.monster/docs/install-with-ai).

- Ask the user for the server's SSH access, the domain and the certificate email (also which email the administrator uses).
- Never print, read back or store the generated administrator password.
- Finish with the one-time link from `server password-link` and show it in your last message.

**Starting an Automaton app.** Pages, in order: [Build an Automaton app](https://automaton.monster/docs/build-an-automaton-app), [Deploy and publish an app](https://automaton.monster/docs/deploy). Overview for the user: [Your first app](https://automaton.monster/docs/getting-started).

- Wait until the app is `Running` before reporting; `deploy` has no `--yes` flag.
- Publish only if the user asked.
- A team server's API URL comes from its administrator; do not assume the public project website is the user's server.

## Working in an app folder

Before implementing, read the generated `AGENTS.md`, `.automaton/agents/skills/automaton-app/SKILL.md` and `automaton.json`. They are the authoritative workflow for the project. Choose the language and tools from the user's requirements and the Runner environment; do not assume local tools exist on the Runner. For an existing remote app use `automaton link <app-id>` instead of creating another app. More options: [Deploy and publish an app](https://automaton.monster/docs/deploy).

Never paste or print API keys, tokens or passwords. Self sign-up is disabled; users come only from an administrator.

## Documentation

- [Install with your AI agent](https://automaton.monster/docs/install-with-ai): Give your AI agent a server, a domain and an email. It installs Automaton and hands you a one-time link to choose your password.
- [Your first app](https://automaton.monster/docs/getting-started): Describe an app to your AI agent; it builds, deploys and runs it on your server.
- [Automaton by the numbers](https://automaton.monster/docs/numbers): Measured install, update and restore times, server resources, and project activity.
- [Install the server](https://automaton.monster/docs/install-server): Install Automaton (Studio, API, app store, PostgreSQL, RabbitMQ, Traefik) on one x86_64 Linux server with a domain, using one command.
- [Create the first administrator](https://automaton.monster/docs/first-admin): Open the one-time setup link after installation, create the administrator account and sign in to Studio.
- [Add a Runner](https://automaton.monster/docs/deploy-runner): Install a Machine Management Runner on a Linux host with the CLI so Automaton can run your apps.
- [Build an Automaton app](https://automaton.monster/docs/build-an-automaton-app): The app contract in practice; static sites, servers with a runtime, durable data and what to tell a coding agent.
- [Deploy and publish an app](https://automaton.monster/docs/deploy): Validate, deploy and publish an Automaton app from the CLI, check its status, set a marketplace listing, and delete it.
- [Update the server](https://automaton.monster/docs/update-server): Update an installed Automaton server to the latest release from the CLI or Studio, with SSH as the fallback.
- [Back up and restore](https://automaton.monster/docs/backup-restore): Nightly server backups, how to take and list one, and how to restore the database and keys from a backup.
- [Secrets and permissions](https://automaton.monster/docs/secrets-and-permissions): Give an app its credentials with automaton secrets and request platform permissions that an administrator approves.
- [Automaton CLI reference](https://automaton.monster/docs/automaton-cli): CLI commands for creating, linking, validating, deploying, and publishing Automaton apps.
- [automaton.json reference](https://automaton.monster/docs/automaton-json): Reference for the Automaton app identity and generic build, runtime, health, and storage contract.
- [Troubleshooting](https://automaton.monster/docs/troubleshooting): Fixes for apps that do not start after deploy, failing requests, login problems and blank pages.
- [Current limitations](https://automaton.monster/docs/limitations): What Automaton does not do yet, stated specifically.
- [Security overview](https://automaton.monster/docs/security): How an Automaton installation isolates apps, protects secrets and app permissions, audits changes, and what is out of scope.

All of these pages in one file: https://automaton.monster/llms-full.txt

# Automaton app contract

## Application contract

The `application` object in `automaton.json` describes how Automaton builds,
runs, checks, and stores the app.

Automaton does not prescribe a language, framework, package manager, source
layout, build system, or application architecture.

## Generic contract

```json
{
  "application": {
    "build": {
      "image": "runtime-image:tag",
      "command": {
        "executable": "build-tool",
        "arguments": ["build"],
        "workingDirectory": ".",
        "environment": {},
        "useShell": false
      },
      "outputDirectory": "dist",
      "timeoutSeconds": 900
    },
    "runtime": {
      "image": "runtime-image:tag",
      "command": {
        "executable": "app-server",
        "arguments": [],
        "workingDirectory": ".",
        "environment": {},
        "useShell": false
      },
      "port": 8080
    },
    "health": { "path": "/health", "startupTimeoutSeconds": 60 },
    "storage": { "dataDirectory": "data", "mounts": [] }
  }
}
```

`build.command` is optional. When present, Automaton runs its executable with
its arguments, working directory, environment, shell setting, and timeout.
When `build.image` is omitted, `runtime.image` is used.
`build.outputDirectory` is optional and identifies the build artifact to use.

`runtime.command` names the process to start. It is required for a dynamic HTTP
application.
For a new container deployment it requires an explicit `runtime.image`; the image
owns the application process. Historical stored contracts without an image remain
readable, but must declare one before they can be deployed again.
Those apps must provide or depend on an HTTP server in the runtime artifact and
declare it through this contract. A static site instead declares a build command
and `build.outputDirectory`, with no runtime command or Compose contract. Its
build requires an explicit build image; the Machine Management Runner publishes
only the declared output through a shared static serving container. Actions-only
or other finite-work applications with no HTTP endpoint may also omit the runtime
command.

Automaton supplies the container listening port in `AUTOMATON_PORT`, regardless
of the requested `runtime.port`. The process must listen on that port and bind
to `0.0.0.0` (or the equivalent all-interfaces address) inside its container.
Binding only to container loopback (`127.0.0.1`) is not reachable through
Docker bridge publication. Runtime command fields use the same execution rules
as the build command.

Automaton forwards each HTTP request to the runtime. Small responses arrive
complete; responses that stream (Server-Sent Events, or a body with no known
length or larger than one message) are relayed to the browser chunk by chunk as
the app writes them. WebSocket upgrades are relayed too. Request bodies are
still sent whole and are limited in size. One app may hold a limited number of
open streams and WebSockets at once, and one with no traffic for five minutes
is closed, so send a heartbeat. Keep ordinary requests within the server's
configured request timeout.

`health.path` is optional. When configured, readiness requires a successful
2xx HTTP response on that path. `health.startupTimeoutSeconds` limits startup.

`storage.dataDirectory` is the durable application data directory. Automaton
supplies its path in `AUTOMATON_APP_DATA_DIR`. Data there survives runtime
replacement. Build and runtime artifacts are disposable.

`AUTOMATON_API_URL` is the server's public API base URL (no trailing slash), set
in every runtime and Action. Use it to call the Automaton API with an approved
permission key; do not ask the user for it or guess it from your own host.

Use structured commands by default. Set `useShell` only when shell semantics
are required. Keep every managed path inside the application workspace.

Run `automaton validate`, then `automaton deploy`. Deployment is asynchronous.
Success means the deployment operation reaches `Succeeded`. Publishing is a
separate action; publish when authorized by the user's requested delivery.

## Linked guidance

- `llms/automaton-mcp.md`
- `llms/automaton-actions.md`
- `llms/automaton-studio-editor.md`