# Getting Started

## First-Time Setup

Run the interactive setup wizard:

```bash
agentteam onboard
```

The wizard creates `~/.agentteam/`, writes the default configuration, detects available runtimes, can install the daemon as a system service, and finishes by running diagnostics.

To print only runtime detection status and remediation guidance:

```bash
agentteam onboard --runtime
```

AgentTeam Desktop includes Builtin Runtime, which uses the managed OpenCode runtime. OpenCode, Claude Code, Codex, and Kimi Code remain manual PATH or binary configuration paths; `agentteam onboard --runtime` does not install or upgrade them.

## Start the AgentTeam Desktop Client Daemon

Run the AgentTeam desktop client daemon in the foreground:

```bash
agentteam daemon
```

The command reads the local profile, connects this machine to AgentTeam, serves the authenticated local API, starts channel connections, loads runtime/LLM configuration, and accepts agent session traffic. Stop it with `Ctrl+C` or `SIGTERM`.

Useful daemon flags:

| Flag | Meaning |
|------|---------|
| `--host` | Runtime-only bind address override |
| `--port` | Runtime-only listen port override |
| `--server-url` | Save or update a AgentTeam machine server URL before daemon startup |
| `--api-key` | Save or update a AgentTeam machine API key before daemon startup |

The daemon is always headless. On macOS and Windows, start the packaged AgentTeam
application when the Electron window and tray are required.

The canonical AgentTeam machine connect/reconnect command is:

```bash
agentteam daemon --server-url https://agentteam.pingcap.com --api-key <machineApiKey>
```

Browser-based machine connect links can also be handled with:

```bash
agentteam connect 'agentteam://connect?token=...&origin=https%3A%2F%2F...'
```

## System Service

Install agentteam as the platform-native background service:

```bash
agentteam service install
agentteam service start
```

Platform behavior:

| Platform | Service manager | Notes |
|----------|-----------------|-------|
| macOS | launchd | `install`, `uninstall`, `restart`, and `reinstall` are exposed under `agentteam service`; install bootstraps and starts the user LaunchAgent |
| Linux | systemd | `install`, `start`, `stop`, `restart`, `reinstall`, `uninstall`, and `status` support `--user` for a user-level unit |
| Windows | Windows Service | Service start/stop/restart commands are available |

Common commands:

```bash
agentteam status
agentteam status -f json
agentteam service restart
agentteam service reinstall
agentteam service uninstall
```

On macOS, `agentteam service reinstall` starts the LaunchAgent when the previous service was running, and also when reinstall is acting as a first install. On Linux, `agentteam service install` registers and enables the systemd service; run `agentteam service start` if you want to start it immediately. `agentteam status` checks both system and user services by default and shows installed services as active, failed, or inactive. Run the connect command and service commands as the same OS user; if the connection settings are under a regular user, run `sudo agentteam service install` from that user. Use `agentteam status --user` to inspect only the user-level systemd service.

## Logs

```bash
agentteam journal
agentteam journal --tail 50
agentteam journal --head 20
agentteam journal -f
agentteam j -f --tail 20
```

Without flags, `agentteam journal` prints the resolved log path and usage. The default log file is `~/Library/Logs/agentteam/agentteam.log` on macOS, `${TMPDIR:-/tmp}/agentteam/log/agentteam.log` on Linux, and `%LOCALAPPDATA%\agentteam\Logs\agentteam.log` on Windows. Set `log.dir` or `log.file` in `config.yaml` to override it.

The Desktop dashboard **AgentTeam logs** entry shows the latest 500 daemon log lines
and lets you copy the visible log text.

## Configuration

Main configuration file:

```text
~/.agentteam/config.yaml
```

Set `AGENTTEAM_CONFIG_DIR` to move all daemon profile files to another directory.

Current top-level settings:

| Field | Purpose |
|-------|---------|
| `host` | Local API bind host, default `127.0.0.1` |
| `port` | Local API port. `0` means automatic selection: the daemon asks the OS for an available loopback port and persists the selected value. Positive values pin a fixed port and are reused on restart. |
| `pid_file` | PID file path |
| `language` | Default daemon language, default `zh-CN` |
| `default_agent` | Agent used when a conversation has no override or channel binding |
| `ui.theme` | `light`, `dark`, or `system` |
| `ui.color_scheme` | Dashboard color scheme |
| `ui.language` | Dashboard language, `en` or `zh` |
| `ui.show_sidebar_labels` | Sidebar icon+label display mode |
| `log.dir` / `log.file` | Log location |
| `security.public_key` / `security.private_key` | Ed25519 API key signing keys |

## Environment Variables

| Variable | Purpose |
|----------|---------|
| `AGENTTEAM_CONFIG_DIR` | Override `~/.agentteam/` |
| `AGENTTEAM_VERBOSE` | Enable verbose output when set to `1`, `true`, or `yes` |
| `AGENTTEAM_MCP_AGENTTEAMBACK_NO_PROXY` | Control loopback `NO_PROXY` injection for runtime MCP traffic: `auto`, `on`, or `off` |

`AGENTTEAM_MCP_AGENTTEAMBACK_NO_PROXY=auto` is the default. It appends `127.0.0.1`, `localhost`, and `::1` to `NO_PROXY` / `no_proxy` only when the MCP endpoint is local.

## Diagnostics and Upgrade

Run diagnostics:

```bash
agentteam doctor
agentteam doctor --fix-runtime
```

Check and apply upgrades:

```bash
agentteam upgrade
agentteam upgrade --check
```

Print version information:

```bash
agentteam --version
agentteam --version -f json
```