# Container configuration

Source: https://docs.oiy.ai/docs/services/configuration

Configure images, commands, environment variables, ports, and storage.



## Image and command [#image-and-command]

A service uses a container image reference and an optional command array. Pin an image digest when reproducibility matters. The image must be compatible with the selected runtime and provide your dependencies.

The command accepts up to 32 arguments, each up to 4,096 characters. An empty command uses the image’s OCI Entrypoint followed by Cmd. An explicit command replaces both. Arguments retain spaces, empty values and literal dollar signs; shell expansion happens only when you explicitly invoke a shell.

## Environment variables [#environment-variables]

Environment names use letters, digits, and underscores, beginning with a letter or underscore. Up to 64 values are accepted, each up to 8,192 characters. Service reads return environment **names**, not secret values. `NVIDIA_*` names are reserved, case-insensitively, to protect GPU device selection. Select hardware through the resource configuration instead.

A configuration update with `environment` replaces the entire environment map. Omit the field to keep existing values. Do not place API keys in images, templates, command arguments, screenshots, or version control.

## HTTP port [#http-port]

`httpPort` defaults to `8080`. Set it to `null` when no HTTP server is exposed. Valid ports are 1024–65535 except `9090`, which is reserved by the runtime. Your application must listen on the configured port and an appropriate interface.

## Disk and workspace [#disk-and-workspace]

| Setting          | Range                      | Default    |
| ---------------- | -------------------------- | ---------- |
| Container disk   | 5–500 GB                   | 20 GB      |
| Workspace volume | 10–4,096 GB                | 20 GB      |
| Idle sleep       | 1–1,440 minutes, or `null` | 15 minutes |

The container disk is distinct from the persistent `/workspace` mount. Attach independent storage with `volumeId` or create it with `volumeMode: "independent"`. [Storage lifecycle](/docs/storage).

## Update safely [#update-safely]

Read the current revision and send only intended fields in the `patch` object. Image, command, port, or environment changes can restart the service. Review state and logs after an update.

## Image startup requirements [#image-startup-requirements]

The current built-in custom-container contract expects a Linux OCI image configured to run as root, with `/bin/sh`, OpenSSH, and coreutils. Use a catalog starter when you need the preconfigured runtime, and check image compatibility before choosing a minimal or distroless base image. The platform does not automatically make every Docker image compatible.

## Private image access [#private-image-access]

The current preview source supports account-owned pull credentials for one exact, fully qualified repository. Configure access in Settings; matching services and templates select it automatically. Credentials go to the runtime's image-pull mechanism rather than your application environment.

A private-image launch requires the coordinated control-plane and gateway version. See [Private container images](/docs/private-images) for repository scope, rotation, and removal behavior.

## Image versions and retries [#image-versions-and-retries]

The current runtime resolves image tags to a verified manifest digest and captures its command and architecture before allocation. Retries of that operation reuse the captured image version. A later start or restart can resolve a newer version of the same tag; use a digest-pinned reference to keep versions fixed across operations. Public service settings continue to display the original image reference.

Image metadata checks do not prove every required executable exists or that the application will become ready. The image must support the selected placement’s Linux architecture. A terminal-only workload still needs a process that stays running. These startup semantics require the coordinated runtime deployment.