Skip to main content
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.

​
Fields

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

​
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:
Multi-port services must use the list form. Only ports listed get URLs:
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:
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, Amika logs a warning and treats the file as having no service definitions. The [lifecycle] section is still applied normally.

​
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:
Output columns: SERVICE, SANDBOX, PORTS, URL.
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.
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.