> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amika.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Services

> Declare named services with port mappings and URL schemes for your rigs.

Services let you declare network-facing components in `.amika/config.toml` so that rigs automatically publish the right ports and generate URLs when they start.

## Defining services in config.toml

Add `[services.<name>]` sections alongside the existing `[lifecycle]` section. Each section declares a named service with optional port bindings and URL scheme.

```toml theme={null}
[lifecycle]
setup_script = "scripts/setup.sh"

[services.api]
port = 4838
url_scheme = "http"

[services.frontend]
ports = [3000, "3001/tcp"]
url_scheme = [
  { port = 3000, scheme = "https" },
]

[services.sidecar]
port = "9090/tcp"
```

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| `port` | integer or `"port/protocol"` string | no | Single port declaration |
| `ports` | list of integer or `"port/protocol"` string | no | Multiple port declarations |
| `url_scheme` | string or list of `{port, scheme}` tables | no | URL generation for specific ports |

`port` and `ports` are mutually exclusive. A service may omit both to act as a metadata-only entry with no port bindings.

### Port format

Each port value is either:

* **Integer**: interpreted as `containerPort/tcp` (TCP is the default protocol).
* **String** `"containerPort/protocol"`: sets the protocol explicitly, such as `"4982/udp"`.

```toml theme={null}
# These are equivalent
port = 4838
port = "4838/tcp"
```

### url\_scheme

`url_scheme` controls whether Amika generates a URL for a port after resolution. Allowed scheme values are `"http"` and `"https"`.

**Single-port services** accept a string or a list:

```toml theme={null}
# String form: scheme applies to the declared port
[services.api]
port = 4838
url_scheme = "http"

# List form: equivalent to the above
[services.api]
port = 4838
url_scheme = [{ port = 4838, scheme = "http" }]
```

**Multi-port services** must use the list form. Only ports listed get URLs:

```toml theme={null}
[services.web]
ports = [4211, "9872/tcp", "4982/udp"]
url_scheme = [
  { port = 4211, scheme = "http" },
  { port = 9872, scheme = "https" },
]
# 4982/udp gets no URL
```

When `url_scheme` is omitted, no URLs are generated for the service.

## Start service processes

A service declaration publishes ports and records URLs. It does not start the
process. Start services through the repository's lifecycle scripts or process
manager.

Systemd is available for long-running processes that need supervision and
logs. Keep the unit file in the repository, then install and enable it from the
setup script:

```bash theme={null}
sudo install -m 0644 "$AMIKA_AGENT_CWD/.amika/systemd/api.service" \
  /etc/systemd/system/api.service
sudo systemctl daemon-reload
sudo systemctl enable --now api.service
```

Make setup scripts idempotent so rerunning them leaves the service in the same
state.

## Validation rules

Amika validates service definitions when parsing `.amika/config.toml`:

* **Port range:** port numbers must be 1–65535.
* **Protocol:** must be `tcp` or `udp`.
* **Mutual exclusivity:** specifying both `port` and `ports` on the same service is an error.
* **url\_scheme entries** must reference a port declared in the same service. Duplicate port entries within `url_scheme` are rejected.

> [!WARNING]
>
> Container ports **60899–60999** are reserved for internal Amika services and are rejected in service declarations. See [Reserved ports](https://docs.amika.dev/reference/rig-configuration.md#reserved-ports) for details.

If validation fails, rig creation fails with a 400 `invalid_repo_config` error whose message names the problem. Fix `.amika/config.toml` and create the rig again.

## Port resolution

When you run `amika rig create` and the repository contains service
declarations, the hosted provider publishes each declared port. Amika records
the provider's published port and generates a public URL for TCP ports that
declare a `url_scheme`.

Resolved ports and URLs are visible through `amika service list`, rig details,
and API responses.

> [!NOTE]
>
> URL generation only applies to TCP ports. UDP ports with a `url_scheme` do not produce runtime URLs.

## Listing services

Use `amika service list` to inspect published bindings and URLs:

```bash theme={null}
amika service list
amika service list --rig-name teal-tokyo
```

| Flag | Default | Description |
| - | - | - |
| `--rig-name <name>` | (none) | Filter services to a specific rig |

Output columns: `SERVICE`, `SANDBOX`, `PORTS`, `URL`.

```
SERVICE    SANDBOX      PORTS       URL
api        teal-tokyo   4838/tcp    https://api.example.com
metrics    teal-tokyo   9090/tcp    -
```

`amika service list` reports configuration and published endpoints. It does not
connect to the process or check service health. Test the local port or health
endpoint inside the rig.

## Services on the hosted platform

On the hosted Amika platform, service definitions can also be managed through the web UI or the platform API.

**Resolution precedence:** when creating a rig for a repository, the platform resolves service definitions in this order:

1. **Database:** if any service definitions have been saved via the UI or API, use those exclusively.
2. **Repository config:** if no database definitions exist, parse `[services.*]` sections from `.amika/config.toml`.
3. **Default:** if neither source defines services, proceed with no service definitions.

> [!TIP]
>
> **DB-wins-all:** when you save *any* service definition via the UI, it overrides *all* TOML-defined services for that repository. The UI pre-populates from TOML when you first edit, but from that point forward the database is the sole source.

## Services on your own hosts

On a rig that runs on one of your [own hosts](https://docs.amika.dev/guides/byoc.md), services are
reached through the host's `amika-hostd` daemon. The URL that
`amika service list` and the rig details show is a preview URL. Opening it
asks you to sign in to Amika, and only members of your organization get
through. Where it points depends on the host's [transport](https://docs.amika.dev/guides/byoc.md):

| Transport | Service URL |
| - | - |
| `tunnel` (the default) | Its own subdomain, `https://<service>--<rig>.r.<org>.o.amika.run/` |
| `listen` | A path on the URL the host registered, `<registered-url>/v0beta1/rigs/<rig>/previews/<service>/` |

A listening host's previews work only when it registered a bare HTTPS hostname,
such as `https://hostd.example.com`, with no path or port. Its previews share
one origin, so open one at a time: root-relative assets, such as a Vite or
Next.js dev server's, follow the preview you opened last.

### Service tokens

Browsers use the URLs above. For a script or `curl`, mint a service token:

```bash theme={null}
curl -X POST \
  "https://app.amika.dev/api/v0beta1/rigs/<rig>/services/<service>/tokens?ttl_seconds=900" \
  -H "Authorization: Bearer $AMIKA_API_KEY"
```

| Response field | Description |
| - | - |
| `url` | The service's address on the host, ending in `/`. It carries no credential |
| `header` | The header to send the token in, as `Bearer <token>`: `X-Amika-Authorization` |
| `token` | The token |
| `expires_at` | When the token expires |

`ttl_seconds` is optional: tokens last an hour by default and at most a day
(`86400`). The endpoint answers `403 service_token_forbidden` for `amikad`. It
works only for rigs on your own hosts.

## Related docs

* [Rig configuration](https://docs.amika.dev/reference/rig-configuration.md): lifecycle scripts, Git cloning, reserved ports
* [CLI reference](https://docs.amika.dev/reference/cli.md): full command and flag index


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.