Quickstart: your first agent in 10 minutes

This guide takes you from a fresh checkout to chatting with your first agent. Five steps, ten minutes.

The goal

A running Platos instance, a linked provider key, an agent named "Hello", and a successful chat turn. After this, you have everything you need to explore the rest of the docs.

Steps

1. Clone and configure.

   git clone https://github.com/platos-labs/platos.git
   cd platos
   cp .env.example .env
   

   Generate two keys:

   echo "ENCRYPTION_KEY=$(openssl rand -hex 16)" >> .env
   echo "PLATOS_MESSAGE_ENCRYPTION_KEY=$(openssl rand -hex 16)" >> .env
   

2. Start the stack.

   docker compose -f docker-compose.platos.yml up -d --build
   

   First boot pulls images and runs migrations; allow 5 minutes.

3. Sign in.

   Open http://localhost:3030. In dev mode the magic-link flow auto-completes (no real email is sent). Use any email you like; the convention is local@platos.dev. You land on a default project with a single environment dev.

4. Add a provider key.

   Provider keys live in environment variables, not in a separate dialog. Open your .env file and add the variable for whichever provider you have:

   echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env
   # or
   echo "OPENAI_API_KEY=sk-..." >> .env
   

   Restart the stack so the new env propagates into the running containers:

   docker compose -f docker-compose.platos.yml up -d
   

   The Providers page in the sidebar shows the provider as linked and runs a health check on the key. Within a few seconds the model picker fills in.

5. Create the agent.

   Sidebar -> Agents -> "New agent".

   • Name: Hello.
   • Model: pick any model from your provider.
   • System prompt: You are a friendly assistant. Reply concisely.

   Save. The agent detail page opens. Click "Chat", type "Hi", and watch tokens stream.

Verify

• The chat panel streams tokens. The first token arrives in under a second.
• The agent's monitoring tab shows one turn and a non-zero cost.
• The runs tab in the sidebar lists no runs (a chat turn is not a BGO).

Next steps

• Add a provider key for a deeper walk through provider config.
• Create your first agent for the wizard's full feature set.
• Connect an entity (TypeScript) to give your agent tools.
• Self-host with docker compose for production deployment.
• The reference entity backend lives at references/entity-hello-world/ (drift D-010 noted: install with its own package.json, not from the workspace root).