# Quickstart
> Source: https://useagentos.dev/docs/core/quickstart

This guide gets AgentOS installed, configured, and running locally. It
assumes you want the standard product experience: terminal commands, local Web
UI, Pilot Router, memory/search support, and safe local defaults.

## Requirements

- Python 3.12 or newer for terminal installs.
- `uv` for the recommended terminal install.
- Git, Git LFS, and Node.js 22 or newer only when installing from source.
- A provider API key unless you use a local provider such as Ollama.

## Recommended Install

Install the current release (recommended extras included) by following the
[Installation](https://useagentos.dev/docs/core#installation) section of the README. The newest
release assets are always on the
[Releases page](https://github.com/use-agent-os/agent-os/releases/latest).

The `recommended` extra includes Pilot Router dependencies and memory/search
support used by the default product experience.

If `agentos` is not found after install, open a new shell or run:

```sh
uv tool update-shell
```

## First-Run Setup

Interactive setup:

```sh
agentos onboard
```

Script-friendly setup:

```sh
export OPENROUTER_API_KEY="sk-..."
agentos onboard --provider openrouter --api-key-env OPENROUTER_API_KEY
```

Useful variants:

```sh
agentos onboard --if-needed
agentos onboard --minimal
agentos onboard --provider openai --api-key-env OPENAI_API_KEY
agentos onboard --provider ollama --model llama3.1
```

`--if-needed` is safe for install scripts because it avoids rewriting an
already-ready setup. `--minimal` configures the provider path and skips optional
channels/search/image-generation sections.

Check onboarding state:

```sh
agentos onboard status
```

## Run the Gateway

Foreground gateway:

```sh
agentos gateway run
```

Background gateway with readiness wait:

```sh
agentos gateway start --json
agentos gateway status
```

Default address:

```text
http://127.0.0.1:18791/control/
```

The gateway defaults to loopback for safety. To bind elsewhere, opt in:

```sh
agentos gateway run --listen 0.0.0.0 --port 18791
```

Only expose a non-loopback gateway behind appropriate auth and network controls.

## First Useful Run

Open the Web UI:

```text
http://127.0.0.1:18791/control/
```

Start terminal chat:

```sh
agentos chat
```

Run one automation turn:

```sh
agentos agent -m "Inspect this workspace and suggest a test plan"
```

Run a one-shot task in a specific workspace:

```sh
agentos agent \
  --workspace /path/to/project \
  --workspace-strict \
  -m "Review the current diff and list the highest-risk changes"
```

Use the Web UI for browser-based chat, approvals, setup, channels, usage, and
logs. Use `agentos chat` when you want a terminal conversation. Use
`agentos agent` for one-shot automation.

## Resume Work

Resume a terminal chat session:

```sh
agentos chat --session <session-key>
```

Inspect sessions:

```sh
agentos sessions list
agentos sessions show <session-key>
agentos sessions export <session-key>
```

Export a session when exact history matters for debugging or handoff.

## Check Readiness

Run these after setup:

```sh
agentos doctor
agentos providers list
agentos search list
agentos channels types --json
```

If the gateway is running, inspect runtime status:

```sh
agentos gateway status
agentos providers status
agentos channels status
agentos memory status
```

For provider/model selection details, see
[Providers and Models](https://useagentos.dev/docs/core/providers-and-models). For search setup, see
[Web Search](https://useagentos.dev/docs/core/search).

For gateway lifecycle, host/port, and exposure guidance, see
[Gateway](https://useagentos.dev/docs/core/gateway).

## Stop or Restart

Foreground gateway:

```text
Ctrl+C
```

Managed background gateway:

```sh
agentos gateway stop
agentos gateway restart
```

## Upgrade

Upgrade to the latest release. `agentos upgrade` also restarts the
gateway and verifies it reports the new version, so it is preferred
over calling `uv tool` yourself:

```sh
agentos upgrade
```

It installs the published release of `use-agent-os[recommended]` — the
same extras profile `install_source.sh` uses — pinned to the Python
version already running AgentOS. Your configuration and data in
`~/.agentos/` are not touched. To check the installed version, run
`uv tool list`.

`agentos upgrade` never installs from a local checkout: only
`bash scripts/install_source.sh` rebuilds the React control UI before
installing. If you installed from source, re-run that script. See the
[README upgrade section](https://useagentos.dev/docs/core#upgrade).

## Next Steps

After the first run:

1. Configure search if you want web research:
   [Web Search](https://useagentos.dev/docs/core/search).
2. Enable channels if you want Slack, Telegram, Discord, or another
   messaging surface: [Channels](https://useagentos.dev/docs/core/channels).
3. Review memory behavior if you want durable recall:
   [Memory](https://useagentos.dev/docs/core/features/memory).
4. Review tool permissions before unattended automation:
   [Tools, Approvals, and Sandbox](https://useagentos.dev/docs/core/tools-and-sandbox).
5. Learn Pilot Router if you want cost-aware model routing:
   [Pilot Router](https://useagentos.dev/docs/core/features/pilot-router).
6. Use the glossary if product terms are unfamiliar:
   [Glossary](https://useagentos.dev/docs/core/glossary).

## Install From Source

Use source install when you want a checkout-backed install:

```sh
git lfs install
git clone https://github.com/use-agent-os/agent-os.git
cd agent-os
git lfs pull --include="src/agentos/memory/models/**"
git lfs pull --include="src/agentos/agentos_router/models/**"
bash scripts/install_source.sh
```

For development, use the repository virtual environment:

```sh
uv sync --extra recommended --extra dev
uv run agentos --help
uv run agentos gateway run
```

When developing from source, prefix commands with `uv run` so they use the
checkout you are editing.
