Agents in containers,
within reach.

An agent in a container is walled off from your Mac, so it can’t tell Gnista it needs you. Give the container Gnista’s helper and a way back, and its sessions get rows in the notch like any other. Here’s how for a devcontainer on your Mac, a container on a server, and a Kubernetes pod.

Try free for 7 daysNo account, no card · then €19 once

Updated

The short answer

  • On your Mac: turn on Settings ▸ Remote ▸ Agents in containers, add the lines it shows to your devcontainer.json, and rebuild the container.
  • On a server Gnista connects: mount the server’s ~/.gnista into the container in the same way.
  • In Kubernetes: in Settings ▸ Remote, choose Other Host… and type kube:, the context, namespace and pod.

Devcontainers on your Mac

  1. In Gnista’s Settings ▸ Remote, turn on Agents in containers. Gnista makes a folder for containers, ~/.gnista/containers, with its helper for Linux on both processors.
  2. Click Copy under the lines it shows, and add them to your project’s devcontainer.json.
  3. Rebuild the container. When it’s created, it connects the agents installed in it.
  4. Start a session in the container. Its row shows Docker as the machine.

The lines

"mounts": ["source=${localEnv:HOME}/.gnista/containers,target=/opt/gnista,type=bind"],
"containerEnv": { "GNISTA_HOME": "/opt/gnista" },
"postCreateCommand": "/opt/gnista/bin/gnista install all"

Without a devcontainer, mount the same folder into any container, then run /opt/gnista/bin/gnista install all in it once:

docker run -it -v ~/.gnista/containers:/opt/gnista -e GNISTA_HOME=/opt/gnista your-image

How it works

Docker Desktop passes no sockets from your Mac into containers, so Gnista listens on a port on your Mac’s loopback, which containers reach as host.docker.internal. Each connection must start with a password kept in the folder you mount, so other apps on your Mac can’t send. arm64 and x86_64 images both work.

Containers on a server

First connect the server: agents over SSH. Then mount its ~/.gnista into the container, with the same lines as above but ${localEnv:HOME}/.gnista as the source. The container’s user must be root, or have your user ID on the server, to reach the socket there.

Kubernetes pods

  1. Install kubectl on your Mac, with Homebrew or Rancher Desktop, and check kubectl exec reaches the pod.
  2. In Gnista’s Settings ▸ Remote, click Connect, choose Other Host… and type kube: with the context, namespace and pod, such as kube:prod/agents/agent-0. A deployment works too: kube:prod/agents/deploy/agents.
  3. Gnista sets the pod up through kubectl exec, as it would a server, and keeps a relay running over it for the agents’ events. When the pod restarts, Gnista sets it up again.

Limits

  • Anyone who can run commands in the container or pod can answer your approvals, as on a server. Connect the ones you trust.
  • Sessions in containers on your Mac all show as Docker, not by container. A click brings up the terminal tab running docker exec or kubectl exec into it.
  • Linux containers and pods only, x86_64 or arm64.
  • When your cloud login for kubectl expires, the pod’s row says it needs you; log in again as you would for kubectl, and Gnista tries again by itself.
  • Organisations that turn remote machines off for their Macs turn this off too: managed settings.

More guides.