Skip to main content

Your first agent

After declaragent --version prints cleanly, scaffold an agent from the built-in template catalog.

Run the wizard​

declaragent init

The wizard walks you through:

  1. Pick a provider. Anthropic (recommended — Claude), OpenAI, or OpenRouter. Local providers (Ollama, LM Studio, llama.cpp) are also offered for offline laptops.
  2. Authenticate. Browser PKCE for OpenRouter, paste-key for the rest.
  3. Pick a template. Start with concierge — it has no webhook, so it runs on any laptop behind NAT.
  4. Verify. The wizard fires one hello call at the selected model to confirm the API key works.

Non-interactive mode (for CI):

declaragent init \
  --template concierge \
  --provider anthropic \
  --skip-verify

See declaragent init --help for every flag.

What got scaffolded​

The concierge template produces:

./
├── agent.yaml
├── .env.example
├── skills/
│   └── concierge.md
└── README.md           # quickstart for THIS agent

agent.yaml is the only file you edit regularly. Everything else is starter scaffolding you can re-generate.

Talk to it​

declaragent

This starts the interactive REPL. Ask it anything about the current directory — the concierge template lets the agent use the built-in Read / Glob / Grep tools to find answers.

Run it as a service​

Once you've added an event-sources.yaml (webhook, cron, or file-watch), bring the agent online with the docker-compose-style lifecycle verbs:

declaragent up -d        # start in the background; prints a pid
declaragent ps           # shows which agents are bound + their sources
declaragent logs -f      # tail per-agent event logs
declaragent down         # stop everything

up without -d runs in the foreground and exits on Ctrl-C. Re-running up while something's already bound reloads — the old process stops cleanly before the new one binds. State lives under ~/.declaragent/ (up.pid, up-state.json, logs/<agent-id>.log).

Screenshots​

Screenshot: init wizard provider picker — placeholder, landing 2026-Q2.

Screenshot: REPL hello message — placeholder, landing 2026-Q2.

[placeholder — landing 2026-Q2] Real screenshots captured against the v1.0 build.

Next steps​