Accessing Octelium Services

Every Workspace is connected to the Cluster with its own Octelium Session, which lets the tools running inside it reach the Octelium Services that its owner is authorized to access, by name and without any credential (read more here). This example walks through a development Workspace for the payments team that uses an internal HTTP API, a PostgreSQL database, a Kubernetes cluster, an SSH server and an MCP server, none of whose credentials are present in the Workspace.

The Services

The following Octelium Services are created by a Cluster administrator. Each one stores its upstream credential as an Octelium Secret (read more about each mode here):

kind: Service
metadata:
  name: ledger-api.payments
spec:
  mode: HTTP
  config:
    upstream:
      url: https://ledger.internal.example.com
    http:
      auth:
        bearer:
          fromSecret: ledger-api-token
---
kind: Service
metadata:
  name: pg-staging.payments
spec:
  mode: POSTGRES
  port: 5432
  config:
    upstream:
      url: postgres://pg-staging.internal.example.com
    postgres:
      user: payments_dev
      database: payments
      auth:
        password:
          fromSecret: pg-staging-password
---
kind: Service
metadata:
  name: k8s-staging
spec:
  mode: KUBERNETES
  config:
    upstream:
      url: https://k8s-staging.internal.example.com:6443
    kubernetes:
      kubeconfig:
        fromSecret: k8s-staging-kubeconfig
---
kind: Service
metadata:
  name: bastion-eu
spec:
  mode: SSH
  config:
    upstream:
      url: ssh://bastion-eu.internal.example.com
    ssh:
      user: deploy
      auth:
        privateKey:
          fromSecret: bastion-eu-key

The members of the payments Group are then allowed to access them via a Policy, which also applies to their Workspaces since every Workspace run is a Session of its owner (read more about Policies here).

Using the Services

Inside any of the team's Workspaces, the Services are used with their standard clients:

octelium get service

# The internal HTTP API
curl -s http://ledger-api.payments/v1/accounts/acc_7Hq2/balance | jq

# The staging database
psql -h pg-staging.payments -c "SELECT count(*) FROM transfers WHERE status = 'pending';"

# The staging Kubernetes cluster
octelium cfg k8s-staging
export KUBECONFIG="$HOME/.kube/k8s-staging.$OCTELIUM_DOMAIN"
kubectl -n payments get pods

# The bastion host
ssh bastion-eu

Since psql expects a database user and Octelium injects the real one, any user name works on the client side. Applications use the same addresses, for example via DATABASE_URL=postgres://pg-staging.payments:5432/payments and LEDGER_API_URL=http://ledger-api.payments.

Using the Services in Tasks

Lifecycle tasks that access Octelium Services must be POST_START tasks, since the Workspace connects to the Cluster at the beginning of the POST_START phase, and they should wait until the connection is established (read more here). Here is a Template that refreshes a local copy of reference data from the staging database every time the Workspace starts:

spec:
  image:
    registry:
      url: postgres:18
  runtime:
    tasks:
      - name: sync-reference-data
        type: POST_START
        workingDir: /workspace
        onFailure: ON_FAILURE_ABORT
        run: |
          timeout 120 sh -c 'until getent hosts pg-staging.payments > /dev/null; do sleep 2; done'
          pg_dump -h pg-staging.payments -t currencies -t fee_schedules -Fc -f /workspace/reference.dump payments

Connecting AI Agents to MCP Servers

MCP servers can be exposed as Octelium MCP Services too, which gives AI agents running in Workspaces access to tools such as issue trackers, observability backends or internal knowledge bases, again without any token in the Workspace (read more about MCP Services here). Here is an MCP Service for a remote MCP server that requires a bearer token:

kind: Service
metadata:
  name: linear
spec:
  mode: MCP
  config:
    upstream:
      url: https://mcp.linear.app/mcp
    mcp:
      endpoint: /mcp
      auth:
        bearer:
          fromSecret: linear-api-key

And here is how Claude Code is configured to use it from inside a Workspace:

claude mcp add --transport http linear http://linear/mcp

Auditing

Every request made through these Services, including the HTTP paths, SQL queries, Kubernetes API calls, SSH sessions and MCP tool calls, is logged by Octelium with the identity of the User and of the Workspace that made it (read more here). To restrict what the Workspaces can do further, for example by allowing a Template's Workspaces only read-only queries, read this guide.