> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Configure model access, then choose a local or remote environment for your first runs.

## Configure Model Access

Start a local GLM-5.2 endpoint with an OpenAI-compatible chat API, then export its connection settings. Use valid shell variable names with underscores:

```bash theme={null}
export MODEL_BASE_URL="http://localhost:8000/v1"
export MODEL_API_KEY="EMPTY"
```

Use the real key instead of `EMPTY` if your local server enforces authentication. The examples below pass these values into each run and use the `openai-chat` API protocol.

```bash theme={null}
agentcompass run \
  swebench_verified \
  mini_swe_agent \
  glm-5.2 \
  --env docker \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --model-api-protocol openai-chat \
  --task-concurrency 1
```

## Check SWE-bench Dependencies

SWE-bench Verified and mini-SWE-agent use optional dependencies that are not part of the minimal install. Install them in the active environment before running the quick start:

```bash theme={null}
uv pip install -r requirements/swe.txt
uv pip install -r requirements/mini-swe-agent.txt
```

The Docker quick start also needs a working Docker daemon and access to pull the SWE-bench task image inferred by the recipe:

```bash theme={null}
docker version
```

## Recommended Config Setup

Keep secrets in environment variables, and use YAML config files for defaults you want to reuse. `agentcompass config show` prints YAML by default. Without component selectors it prints the global `runtime` and `execution` sections, which is useful for user-level or project-level defaults:

```bash theme={null}
mkdir -p ~/.config/agentcompass

agentcompass config show > ~/.config/agentcompass/config.yaml
```

Project-level defaults can live in `<repo-root>/config.yaml`:

```bash theme={null}
agentcompass config show > config.yaml
```

For a run-specific editable template, pass the components you plan to use. The selected benchmark, harness, and environment defaults are included in the YAML:

```bash theme={null}
mkdir -p configs

agentcompass config show --benchmark swebench_verified --harness mini_swe_agent --env docker > configs/swebench-glm52-docker.yaml
```

Apply that file when starting the run:

```bash theme={null}
agentcompass run \
  swebench_verified \
  mini_swe_agent \
  glm-5.2 \
  --config configs/swebench-glm52-docker.yaml \
  --env docker \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --model-api-protocol openai-chat \
  --task-concurrency 1
```

Use `agentcompass config docs <kind> <component-id>` to inspect fields before editing a component block:

```bash theme={null}
agentcompass config docs benchmark swebench_verified
agentcompass config docs harness mini_swe_agent
agentcompass config docs env docker
```

## Quick Start

<Note>
  Start with one SWE-bench Verified instance before increasing concurrency or removing `sample_ids`.
</Note>

### Docker Smoke Test

Run one SWE-bench Verified task with mini-SWE-agent in Docker against your local GLM-5.2 endpoint:

```bash theme={null}
agentcompass run \
  swebench_verified \
  mini_swe_agent \
  glm-5.2 \
  --env docker \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --model-api-protocol openai-chat \
  --model-params '{"temperature":0}' \
  --task-concurrency 1
```

### Remote Sandbox

Remote sandboxes require provider credentials. They are the preferred path for heavier terminal and coding benchmarks because recipes can select task images and workspace roots from benchmark metadata.

#### Daytona: Single SWE-bench Verified Instance

Use Daytona to run the same SWE-bench smoke test without consuming local Docker compute:

```bash theme={null}
export DAYTONA_API_KEY="..."

agentcompass run \
  swebench_verified \
  mini_swe_agent \
  glm-5.2 \
  --env daytona \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
```

This is a good provider smoke test: `sample_ids` limits the run to one task, and the Daytona recipe can infer the SWE-bench task image and workspace from metadata.

#### Modal: Full SWE-bench Verified With Concurrency

Use Modal to run the complete SWE-bench Verified benchmark with concurrent tasks:

```bash theme={null}
export MODAL_TOKEN_ID="..."
export MODAL_TOKEN_SECRET="..."

agentcompass run \
  swebench_verified \
  mini_swe_agent \
  glm-5.2 \
  --env modal \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --task-concurrency 32
```

Because this command does not set `sample_ids`, it runs the full benchmark split. Lower `--task-concurrency` if your model endpoint or sandbox provider has tighter rate limits.

<Note>
  For benchmark/provider combinations with recipes, image and workspace root are usually inferred from task metadata. You do not need to pass `image` in `--env-params` unless you intentionally want to override the recipe.
</Note>

<CardGroup cols={2}>
  <Card title="Model API setup" icon="plug" href="/cookbooks/first_runs/model_api_setup">
    Learn protocol and judge-model configuration.
  </Card>

  <Card title="Environment selection" icon="box" href="/cookbooks/first_runs/environment_selection">
    Choose local, Docker, Daytona, Modal, or cluster-backed execution.
  </Card>
</CardGroup>