Quickstart

From zero to running in four commands.

Four commands, one API key, one running agent on localhost:8080. Below is the same flow as the homepage Quickstart, expanded with what each step does, what files it creates, and what to do when it doesn’t work.

For the full reference (every flag, every config option), the augment-1 README and the docs/ folder on GitHub are authoritative.

Prerequisites

Three things on your machine.

  • Bun 1.2 or newer. Install from bun.sh if you don’t have it. curl -fsSL https://bun.sh/install | bash
  • An API key from Anthropic, OpenAI, or OpenRouter, or a local/remote Ollama model. Auggy ships with first-party adapters. The default scaffold uses Anthropic — switch in agent.yaml if you want a different provider.
  • A terminal. macOS, Linux, or WSL. Native Windows is not yet officially supported (untested).
Steps

Four commands.

  1. 01

    Install Auggy

    Auggy publishes the auggy CLI on npm. Bun runs the TypeScript runtime.

    npm i -g auggy

    Verify: auggy --version

  2. 02

    Scaffold an agent

    The wizard asks for an engine, model, display name, operator name, and purpose. The default augments are chat-ready.

    auggy create my-agent

    Creates ./my-agent/ with agent.yaml, identity.md, learned.md, .env, skills/, augments/, and data/.

  3. 03

    Open the agent

    Move into the project and fill the provider key in .env. You can also edit identity.md now, or leave it for later.

    cd my-agent
# edit .env:
# ANTHROPIC_API_KEY=sk-ant-...

    Get a key from console.anthropic.com (or platform.openai.com / openrouter.ai).

  4. 04

    Run it

    auggy run starts the agent in foreground and opens local chat. Ctrl-C stops it.

    auggy run

    Prints /console/chat, /console, /health, and / home URLs.

What just happened

You composed an agent from primitives.

auggy create wrote an agent.yaml: an engine pick (which model does the reasoning) plus a list of augments (what the agent can do). When you ran auggy run, the kernel loaded each augment, wired their tools into a capability table gated by trust level, and started serving the web transport on port 8080.

Fresh agents include identity and learned file memory, scoped filesystem access, browser chat, web fetch, and turn control. Optional augments like knowledge, notify, and Telegram are installed after the first chat works.

Troubleshooting

When it doesn’t work.

command not found: auggy

Cause: Your npm global bin is not on PATH, or the global install failed.

Fix: Run `npm config get prefix`, ensure its bin directory is on PATH, then reinstall with `npm i -g auggy`.

missing ANTHROPIC_API_KEY

Cause: The .env file isn't being loaded, or the key is empty.

Fix: Confirm my-agent/.env exists and has ANTHROPIC_API_KEY=sk-ant-... on its own line. Run `auggy doctor` from the agent directory.

EADDRINUSE: address already in use 8080

Cause: Another process is bound to port 8080.

Fix: Edit agent.yaml, change webTransport.options.port to something free (e.g. 8090). Restart.

agent boots but every reply says 'I'm an AI assistant'

Cause: The identity.md is still the scaffold default.

Fix: Edit my-agent/identity.md — give the agent a sharper purpose and operator-authored rules. Restart.

Hit something else? Open an issue at github.com/looselyorganized/augment-1/issues — or check the existing ones, you’re probably not first.

What’s next

You have a running agent. Now what?

Add knowledge

Install the knowledge augment, then edit local markdown or wire API-backed sources.

Add notifications

Install notify for outbound operator alerts. It starts with a local notifications.jsonl destination.

Deploy to Railway

Run auggy deploy from the agent directory. Auggy stages the agent, pushes secrets, and verifies health.

Add MCP tools

Install the MCP augment, then configure local stdio or remote HTTPS MCP servers in .mcp.json.

Try another engine

Swap provider in agent.yaml — Anthropic, OpenAI, OpenRouter, or Ollama.

Star us, fork us, file issues.

Auggy is Apache-2.0 and built in the open. The README on GitHub is the authoritative reference.

★ GitHubRead the README