Services

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.

[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".

# 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:

# 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:

[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:

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.

Container ports 60899–60999 are reserved for internal Amika services and are rejected in service declarations. See 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.

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:

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:

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

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, 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:

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:

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.

Rig configuration: lifecycle scripts, Git cloning, reserved ports
CLI reference: full command and flag index

CLI and platform

Repository configuration

HTTP API

Defining services in config.toml

Fields

Port format

url_scheme

Start service processes

Validation rules

Port resolution

Listing services

Services on the hosted platform

Services on your own hosts

Service tokens

​Defining services in config.toml

​Fields

​Port format

​url_scheme

​Start service processes

​Validation rules

​Port resolution

​Listing services

​Services on the hosted platform

​Services on your own hosts

​Service tokens

​Related docs

Defining services in config.toml

Fields

Port format

url_scheme

Start service processes

Validation rules

Port resolution

Listing services

Services on the hosted platform

Services on your own hosts

Service tokens

Related docs