Socket Deployment Types

Pod-OS runs a Socket Actor's software for you. There are two deployment types, and they differ in who builds the artifact and how Pod-OS starts it. Both are configured under GitHub / GitLab Integration when you deploy a new Gateway (Deploy Actor Network) or add an Actor to an existing Gateway (Add Actor).

Both types end up doing the same two things at runtime—register with the Gateway and answer health probes (StatusRequest → Status)—and both keep :62312 open for the Kubernetes readiness probe. The choice is only about packaging.

Reference examples (public repositories)

Pod-OS publishes a minimal, production-shaped reference repository for each type. Clone them, deploy them straight from the dashboard, or use them as templates:

Each README includes build steps, the exact dashboard field values, and podos CLI verification commands. The gateway-starts-matrix covers Startup Script Path, Build Command, and inline Startup Script for Go, Rust, Python, and Java — with local and production test steps in each cell.

Type 1: Self-registering container

Use this when CI builds a Docker image and pushes it to a registry such as GitHub Container Registry (ghcr.io).

How it works

CI (GitHub Actions) builds Dockerfile → pushes ghcr.io/<org>/<repo>:main
  └─ Pod-OS pulls the image and runs it, injecting PODOS_* env vars
       └─ your process listens on :62312   (Kubernetes tcpSocket readiness)
       └─ SDK client dials the Gateway and registers as a Socket Actor
            └─ RespondToHealthChecks(client)  (answers StatusRequest)

Pod-OS passes Gateway connection details to your container as environment variables:

The SDK reads these for you via config.ConfigFromEnv().

Dashboard configuration

• Integration Category: Self-registering container (image from CI)
• Repository URL: https://github.com/<org>/<repo>
• Branch / Tag: main (or the tag your CI publishes)
• Container Image Override (recommended): the lowercase GHCR path, e.g. ghcr.io/<org>/<repo>:main

If the image is private, enable the image-pull-secret option and supply a GitHub username plus a Personal Access Token with read:packages.

Registry paths are lowercase. GitHub org/repo names may be mixed case, but the published image path is always lowercase (ghcr.io/pointofdata/...). The reference workflow lowercases this for you. If no package appears after a push, check the repo Actions tab—a repository name must be lowercase error means nothing was pushed.

Type 2: Gateway starts software

Use this when your Actor runs as a process the Gateway starts—not as a prebuilt container you register yourself. Pod-OS clones your Git repository into the pod before the Actor starts.

This mode runs executables or scripts only. You cannot start a separate container image this way.

How it works

Pod startup
  └─ Pod-OS clones your repo → /workspace/repo
       └─ (optional) runs your Build Command
            └─ runs your Command Path / Startup Script
                 └─ your process listens on :62312 and registers with the Gateway
                      └─ RespondToHealthChecks(client)  (answers StatusRequest)

The default runtime image has bash and the Pod-OS binaries only—no language toolchain at runtime.

For Python or Java scripts, select a platform Runtime flavor in the dashboard. Flavor images extend the actor base with the language and the matching official SDK:

Go and Rust SDKs are compile-time: use Default and commit a static binary (as the Go reference repo does), or use Type 1 with a custom image. Heavy custom dependencies still belong in Type 1 (FROM a flavor image in your own Dockerfile).

Dashboard configuration

• Integration Category: Gateway starts software (clone repo)
• Runtime: Default, Python, or Java (Socket actors)
• Repository URL: https://github.com/<org>/<repo>
• Branch / Tag: main
• Clone Path: /workspace/repo (default)
• Command Path / Startup Script Path: the runnable entry point after clone, e.g. /workspace/repo/path/go/bin/start.sh (full 3×4 matrix: examples/socket-git-ci/gateway-starts-matrix/ in this repo)
• Build Command (optional): e.g. cd /workspace/repo/build-command/python && pip install --break-system-packages -r requirements.txt
• Startup Script (inline) (optional): bash script content stored in a Kubernetes secret when you do not commit bin/start.sh to the repo

Private repositories require a Personal Access Token with repository Contents: Read. Pod-OS stores it in a Kubernetes secret used only by the git-clone init container.

Picking up changes after deploy

After the initial deploy, use the right control depending on what changed:

Source sync (POST /actors/:id/source-sync) force-pulls the configured container image (Type 1, with imagePullPolicy: Always) or reclones the configured git ref (Type 2) and restarts the pod. It does not change dashboard configuration — only refreshes what is already configured.

Save Changes always redeploys shell/socket actors and persists form updates to the compute record. For Type 1 actors tracking a mutable tag like :main, use Source sync when CI publishes a new image without changing the tag.

Update to current platform image applies only to platform-managed runtime images (Type 2). It does not apply to Type 1 custom CI images.

Choosing between them

For a field-by-field deployment walkthrough (PAT scopes, dashboard options, troubleshooting), see Deploy Actors with GitHub.

Verifying health

From inside the cluster, dial the Gateway load balancer (<gateway>-lb:62312) and probe the Actor with the podos CLI:

# A Socket (non-Neural-Memory) Actor should NOT answer NM queries (times out / errors):
podos send --actor mysocket@mygw.pod-os.com --intent GetEventsForTags --data "health_check=test"

# Once RespondToHealthChecks is live, the status probe returns Status:
podos send --actor mysocket@mygw.pod-os.com --intent StatusRequest

Use the load-balancer socket directly; the AIP binary handshake does not survive kubectl port-forward. For a full walkthrough of using podos during development, see Testing Code Paths with podos.

Next: What is an Evolutionary Neural Memory? — the built-in Actor that stores and connects your data.