Skip to content

Containers

The Containers pages of the console manage Docker on the server: the containers Fadenstack itself runs, and any you add next to it, such as an MCP server or a small service your models call. They do not manage the GPU machines; what runs there is managed through clusters and deployments.

The Containers list: the Running, Not running, Unhealthy and Restarting tiles above Fadenstack's own containers with their class

The list

Open Containers → Containers. It lists every container on the server, Fadenstack's own included. The four tiles count them, and each is also a filter (select it again to list all).

The dashboard's Needs attention list reports containers that keep restarting.

What the tiles and the columns show
Tile Counts
Running Running containers, of all listed
Not running Exited, created or paused
Unhealthy Running, but failing their health check
Restarting Restarting, often in a crash loop
Column What it shows
Name The container's name and short ID
Image What it runs
State Running, exited or paused, and for how long
Class What the console may do with it (below)
Endpoint The host port it is published on, if any
Scope The team or unit that owns it
Actions Start, stop, pause, restart, delete, details: only those its class allows

Classes

A container's class decides what the console lets anyone do with it:

Class For View, logs Start, restart Stop Pause, delete
SYSTEM_CORE Postgres, Redis, the proxy, RabbitMQ, the logs and metrics stores yes yes no no
SYSTEM_AUX Fadenstack's own services and modules yes yes yes no
MCP MCP servers yes yes yes no
TENANT_APP Containers you run yes yes yes yes
UNTRUSTED Anything not classified yes no no no

Change a container's class from its row; SYSTEM_CORE stays locked.

How a container made elsewhere gets its class

A container made elsewhere is classified by its name the first time the list sees it: a name that contains the name of one of Fadenstack's services or of the infrastructure above (redis, postgres and so on) makes a system container, a name that contains mcp- makes MCP, anything else is UNTRUSTED.

Root Mode lifts the class limits for the administrator who activates it, for system maintenance. Select Activate Root Mode, and give a Reason and a Duration. Every action in root mode is audited at high severity.

More about Root Mode

The Reason needs at least 10 characters; the Duration is 60 to 3600 seconds. A container whose policy is locked cannot be stopped, paused, edited or deleted even in root mode.

Get an image

The Images page: Image and Tag with Pull Image, Prune dangling images with Dry Run, and the images on the server

A container starts from an image on the server; creating one does not pull it.

  1. Open Containers → Images.
  2. Enter the image name and tag, and select Pull Image. The progress shows while it downloads.

Prune dangling images removes images no tag points to. It needs Root Mode; try Dry Run first.

Create a container

Create Container: Image, Container Name and Command Override; Class, Policy and Scope; Port Bindings, Environment Variables and Volume Mounts; Start immediately after creation and Networks; and Create Container

  1. On Containers → Containers, select Create.
  2. Fill in Image and a Container Name.
  3. Choose the Class: TENANT_APP for a container of your own, MCP for an MCP server.
  4. Add Port Bindings only if something outside the server must reach it.
  5. Add Environment Variables and Volume Mounts as needed.
  6. Under Networks, choose fadenstack_default so the gateway, the console API and the MCP service can reach it by its name (for example http://my-service:8080).
  7. Turn on Start immediately after creation and select Create & Start, or leave it off and select Create Container to create it stopped.
More about the fields
  • Image: suggestions come from the images on the server.
  • Command Override is optional, written as in a shell.
  • Policy and Scope: set them if you use them.
  • Port Bindings: Fadenstack's services reach the container by name over its network without one. A host port must be free on the server.
  • Networks: without one, the container joins Docker's default bridge.

Note

The console hides values that look secret: variables named like a password, key, token or secret, the password in a URL, and the value after a flag such as --requirepass. The edit form shows them as dots; left as they are, they stay. Each look at a system container's detail or settings is recorded in the audit log. Values the console does not recognise as secret are shown, so name secrets as such.

Only a superuser creates, edits or reclassifies containers. A container that would have root on the server needs Root Mode: one that mounts a folder or file of the server (a host path such as /srv/data, ./config or C:\data; the Docker socket, / and system folders such as /etc among them), or that uses the host network or another container's network. Without Root Mode the console refuses it and says why. Under Volume Mounts, give a name instead of a host path (my-data, not /data/app): Docker keeps a named volume for the container, and it needs no Root Mode. Fadenstack's own volumes are the exception: the database's files, the chat files, the audit trail and the models (fadenstack_pg_data, fadenstack_faden_chat_files and the others its containers use) are mounted only in Root Mode, and the audit log records which volumes a container got. Only the time zone may be mounted read-only without it (/etc/localtime, /etc/timezone, /usr/share/zoneinfo, with :ro).

More about what needs Root Mode
  • Edit: Fadenstack's own containers (SYSTEM_CORE and SYSTEM_AUX) are edited only in Root Mode: a new image or environment for the gateway would read every chat with the key it holds. Their Edit button is greyed out until Root Mode is on.
  • The new container keeps what the form does not show, so an edit needs Root Mode also when the container runs privileged, shares the server's processes or memory, uses its devices (GPUs aside), takes another container's volumes or mounts one of Fadenstack's own.
  • Class: changing the class of a container that has any of the above, or of a SYSTEM_CORE or SYSTEM_AUX container, needs Root Mode; so does unlocking a locked system container.
  • Start, stop and restart need no Root Mode: they run nothing new in the container.

Work with a container

A container's page: its name, class and ID, the Overview and Logs tabs, its status and networks, and Edit

Its page has two tabs:

Tab What it does
Overview State, image, networks
Logs The Last 300 lines, to refresh or download

Stop a container before you delete it: a running one is not deleted. Deleting asks for confirmation; the image stays under Images.

When a container does not stop

A process that ignores the stop signal is killed after ten seconds and shows as Exited (137).

Edit a container

Edit faden-gateway: the notice about the compose file above the form with Image, Container Name, Command Override, Port Bindings, Environment Variables, Class, Policy, Scope, Start after saving and Networks

  1. On the container's page, select Edit. The form opens with what the container was created with.
  2. Change what you need, and select Save and replace.
  3. Confirm.

Docker cannot change these settings in a container that exists, so Save and replace replaces it: a new container is made with the new settings, on the same networks under the same name, and the old container is removed once the new one runs.

Warning

The container gets a new ID, and files it wrote outside its volumes are lost.

More about replacing a container
  • What the form does not show is kept: GPU devices, restart policy, labels, health check.
  • If the new one cannot be made or started (an image that is not on the server, a host port in use), the old one is put back as it was, and the page says why.

The edit form of one of Fadenstack's own containers, with its notice that the next faden deploy or upgrade makes it again without these changes

Fadenstack's own containers can be edited too, for a test or a quick fix, but the next faden deploy or faden upgrade makes them again from the compose file and .env, without your edits; the form says so. The console API's own container cannot be edited from the console: change its settings in ~/fadenstack/.env and run faden upgrade (or faden up).

Networks and stacks

Containers → Networks lists Docker's networks. fadenstack_default is Fadenstack's own; system networks are read-only. You can create a network (optionally internal, without outbound access), inspect one, and delete the ones you created.

Containers → Stacks keeps Docker Compose files under an ID. Deploy Stack saves one; saving again under the same ID makes a new revision. Every revision is kept, two can be compared, and you can roll back to an earlier one. Despite its name, Deploy Stack does not start the containers a file describes: run it with docker compose on the server yourself.

  • MCP servers: an MCP server can run as a container here and be registered by its name on the network.