# Legacy taskstation.toml

Support status and the migration path from v1 taskstation.toml to v2 taskstation.yaml.

Canonical page: https://taskstation.co/docs/project/legacy-toml

This page covers the v1 manifest (`taskstation.toml`, `taskstation_version: 1`). For the current manifest, see [Manifest reference](/docs/project/manifest).

## Support status

TaskStation still supports v1 manifests. The platform resolves a project's manifest in this order: `taskstation.yaml`, then `taskstation.yml`, then `taskstation.toml`. The current starter creates one v2 `taskstation.yaml`. A v1 project keeps working with no forced upgrade.

v1 accepts TOML or YAML syntax. Version 2 accepts YAML only. A v2 manifest written in TOML fails validation.

## Migrate to v2

Create `taskstation.yaml` at the repo root. Set `taskstation_version: 2`.
Convert `[[agents]]` to an `agents:` map, keyed by agent name.
Rename each agent's `env` field to `secrets`. List every secret the agent needs — v2 does not grant secrets by default.
Add `default_agent`, naming the agent that runs by default.
Delete `[[channels]]`. Reconnect each channel from the dashboard.
If you use `[sandbox]` or `[[sandboxes]]`, move each image definition under `sandbox.templates`.
Run `taskstation validate` against `taskstation.yaml`. Fix any error it reports.
Delete `taskstation.toml`.

Agent behavior — system prompt, `model`, `mode`, `temperature`, and more — never moves. It already lives in each agent's `.md` frontmatter under `.taskstation/opencode/agents/`, in both v1 and v2. See [Agents](/docs/project/agents).

Check the result with `taskstation validate --file taskstation.yaml`. Fetch the full v2 schema with `taskstation schema --version 2`. See [CLI reference](/docs/cli) for both commands.

## Key differences

| v1 (`taskstation_version: 1`) | v2 (`taskstation_version: 2`) | Change |
|---|---|---|
| `[[agents]]` (array) | `agents:` (map keyed by name) | Convert each array item to a map entry. |
| `[[agents]].env` | `agents.<name>.secrets` | Renamed. Default flips from `all` to `none` — see the callout below. |
| `[[agents]].model`, `[[agents]].file` | removed | Dead in v1 (parsed, never applied). Agent behavior always comes from the agent's `.md` frontmatter. |
| no `default_agent` | `default_agent` (required) | Must name a declared, enabled agent. |
| `[[channels]]` | removed | Channel routing is dashboard-managed. A connected channel appears as a `connectors:` entry with `provider: channel`. |
| `[sandbox]` (singular, image keys directly on it) | `sandbox.templates` (list) | Move each image into a template entry. |
| `[[sandboxes]]` | `sandbox.templates` | Renamed. |

> **Secrets default to none in v2**
> In v1, an agent with no `env` field gets every project secret by default. In v2, an agent with no `secrets` field gets none. When you migrate, list every secret each agent needs — an agent that silently loses a secret can fail mid-task.

A few `taskstation_cli` actions are legacy-tolerated in v1 (`project.session.exec`, `project.gateway.routing.edit`, `project.schedule.read`, `project.schedule.write`, `project.webhook.read`, `project.webhook.write`, `channel.read`, `channel.connect`, `channel.send`, `channel.disconnect`) — the platform warns but allows them. The same actions are a hard error in v2. Remove them from any agent's `taskstation_cli` grant before you migrate.