Init and Sidecar Containers

When your application starts up, it sometimes needs some preparation work to be done before the main application can run — for example, downloading a file, checking that a database is reachable, or setting up some configuration. Or maybe you need some other application running alongside your main deployment — like a database or a service.

By using Init containers and Sidecar containers, you can fulfill these needs, having them run before or alongside your main Application.

Note - Image Building

Images used by Init and Sidecar containers must be internalized before they can be referenced in the Apps API.

The sidecar container is automatically configured by the platform to expose port 8502. If your sidecar image listens on a port, it must listen on 8502. Port 8501 is reserved exclusively for the main application. Init containers do not need to expose any port. See this Image Building section for details on port requirements.

Init Containers

What is an Init Container?

An init container is a small, short-lived helper that runs this kind of setup work automatically, and only then lets your main application start.

Think of it like a pre-flight checklist: the plane (your app) only takes off after the crew has confirmed everything is ready.

Once an init container finishes its job successfully, it stops — it does not keep running alongside your app. If it fails, it is retried automatically until it succeeds (or the deployment is marked as failed).

Common Use Cases

• Pulling or preparing data — Download a model file, dataset, or configuration from an external source before your app needs it.
• Waiting for a dependency — Wait until a database or external service is reachable before allowing your app to start.
• Setting up files or permissions — Write configuration files or adjust file permissions that your app needs at startup.
• Running database migrations — Apply schema changes to a database before the new version of your app starts serving traffic.

How to Configure an Init Container

Init containers are specified inside the additional_config.init_containers field when creating a deployment. Each init container references an image that has already been internalized into the platform — you only need to provide its name and tag.

The image must be available in your space's container registry. See the Image Internalization guide for how to push images.

Example Request Body

{
  "deploy_name": "my-deployment",
  "image_tag": "some-tag",
  "additional_config": {
    "init_containers": [
      {
        "name": "my-init-container",
        "image_name": "my-init-image",
        "image_tag": "1.0.0"
      }
    ]
  }
}

Field	Description
name	A unique name for the init container within the deployment.
image_name	The name of the internalized image to use for the init container.
image_tag	The tag (version) of the image to use.

You can define multiple init containers — they will run sequentially, one after the other, before your main application starts.

---

Sidecar Containers

What is a Sidecar Container?

A sidecar container is a helper that runs alongside your main application, for the entire lifetime of the deployment. Unlike an init container, it does not stop — it keeps running in parallel with your app.

Think of it like a co-pilot who works at the same time as the pilot, taking care of certain tasks so the pilot can focus on flying.

Common Use Cases

• Log collection — Collect and forward logs from your app to a central logging system.
• Monitoring and metrics — Scrape metrics from your app and expose them to a monitoring platform.
• Proxying or authentication — Sit in front of your app and handle authentication or traffic routing on its behalf.
• Data syncing — Continuously sync data from an external source into a shared location that your main app reads from.

How to Configure a Sidecar Container

A sidecar is specified inside the additional_config.sidecar field when creating a deployment. It references an internalized image by name and tag.

Example Request Body

{
  "deploy_name": "my-deployment",
  "image_tag": "some-tag",
  "additional_config": {
    "sidecar": {
      "image_name": "my-sidecar-image",
      "image_tag": "2.1.0"
    }
  }
}

Field	Description
image_name	The name of the internalized image to use for the sidecar container.
image_tag	The tag (version) of the image to use.

Combining everything

You can combine init containers and a sidecar in the same deployment request, alongside env vars and secrets. Multiple init containers are supported:

Example Request Body

{
  "deploy_name": "my-deployment",
  "image_tag": "some-tag",
  "additional_config": {
    "env_vars": [
      {
        "name": "MY_ENV_VAR",
        "value": "my-value"
      }
    ],
    "secrets": [
      {
        "env_name": "MY_SECRET",
        "secret_name": "my-platform-secret"
      }
    ],
    "init_containers": [
      {
        "name": "my-init-container-1",
        "image_name": "my-init-image-1",
        "image_tag": "1.0.0"
      },
      {
        "name": "my-init-container-2",
        "image_name": "my-init-image-2",
        "image_tag": "1.0.0"
      },
      {
        "name": "my-init-container-3",
        "image_name": "my-init-image-3",
        "image_tag": "1.0.0"
      }
    ],
    "sidecar": {
      "image_name": "my-sidecar-image",
      "image_tag": "2.1.0"
    }
  }
}