Run AXL locally

AXL is a server. You run axl-server, it loads your agents from a configuration directory, and you talk to it over HTTP on port 5000. The axl command line tool is a separate binary that talks to that server for you.

What you need first

Redis with the RediSearch module. AXL keeps sessions, memory, tasks, and search indexes there. The redis/redis-stack-server image has what you need:

docker run -d -p 6379:6379 redis/redis-stack-server

A model provider key. You need at least one. AXL will refuse to start without any, and tells you so: No LLM providers configured. Set at least one API key.

A signing keypair for tokens. AXL authenticates callers with RS256 JSON Web Tokens, so it needs a key to verify them:

axl key generate-jwt

That writes a private and public PEM. Keep the private one private.

If you would rather bring up Redis alongside the optional services - document extraction, S3-compatible storage, an identity provider - the repository root has a compose.yml with all of them. It uses its own ports, so set REDIS_URL to match rather than assuming 6379.

What the first start looks like

• The first start is slower than later ones. AXL embeds a local model for memory and search, and prints Initializing local embedder... while it loads. If you configure no memory and no doc sets, it is skipped entirely.
• Warnings scroll past. TAVILY_API_KEY not set - web tools disabled and similar lines mean an optional feature is off because you have not configured it. (PII_VAULT_KEY is the exception: with any shielded agent it is required, and the server refuses to start without it.) The server is telling you what it turned off.
• A line naming your agents is the real "up" signal - one Agent ready per agent, then the listening line.

Start the server

export CONFIG_DIR=/path/to/axl-config
export REDIS_URL=redis://localhost:6379
export ANTHROPIC_API_KEY=sk-ant-...
export JWT_PRIVATE_KEY="$(cat ~/.axl/keys/jwt_private.pem)"
export JWT_PUBLIC_KEY="$(cat ~/.axl/keys/jwt_public.pem)"

axl-server

Those five are the whole minimum. REDIS_URL defaults to redis://localhost:6379 and PORT defaults to 5000, so you can drop those two if they match your setup. Everything else has a working default; the full list is in the configuration reference.

From a source checkout, the command is cargo run --bin axl-server instead.

Start with just a few agents

By default the server loads every agent listed in agents.toml. While you are finding your feet, it is often nicer to boot one or two and leave the rest alone - startup is quicker, and an agent you have no credentials for cannot distract you with warnings. AGENT_CONFIGS takes a comma-separated list of agent directories, relative to CONFIG_DIR, and uses them instead of the agents.toml list. Each entry points at a directory holding an agent.toml, the same paths agents.toml lists:

export AGENT_CONFIGS=agents/acme/acme-support-agent
axl-server

Skills still come from agents.toml, so agents you name here keep working normally. Unset it whenever you want the full roster back.

Check it came up

curl http://localhost:5000/health

{ "status": 200, "msg": "OK", "data": { "status": "healthy", "version": "0.1.0" } }

/health is the one route that does not need a token. Everything under /api/v1 does.

Get a token

axl config init \
  --jwt-private-key ~/.axl/keys/jwt_private.pem \
  --user-id you@example.com

This mints a token signed with your private key and saves it, so the axl command line tool is authenticated from here on. It does not contact the server; it signs locally with the same key the server verifies against.

It also saves the API URL it will use from now on, defaulting to http://localhost:5000/api/v1. If your server is on another port, say so here or every later command will quietly aim at the wrong place:

axl config init … --api-url http://localhost:5055/api/v1

Three more values have to agree with the server, and config init cannot check them for you because it never calls it. If your deployment overrides any of these, pass the matching flag or verification fails and every call returns 401:

--tenant is different: it sets the token's azp claim, which the server reads as your tenant rather than checking against a configured value. It defaults to default.

Defaults line up out of the box, so on a fresh local setup you need none of these. axl config show prints what was saved.

Say hello

axl agents list

You should see the agents in your configuration directory. Then talk to one:

axl chat <agent-key>

That opens an interactive session. To ask one question and get one answer back - handy for a first smoke test, or for pasting the result into a ticket:

axl chat <agent-key> -m "Hello, what can you do?"

To do the same over HTTP, see the HTTP API.

When it does not start

Read the log first. The server explains itself: it prints one line per agent as it loads, names the file behind any configuration error, and says which optional features it turned off and why.

Next

• Create your first agent
• Use the command line tool
• Call AXL from an application