Run Claude Code on Sevalla

​

At a glance

​

Environment variables

​

How the session works

• One image, one long-lived process. The web process runs start.sh, which clones the repository once, starts a tmux session named claude with Claude Code in it, and then waits. Nothing listens on a port, and with HTTP traffic off nothing on the internet can reach the application.
• The web terminal joins the session. The image sets ENV to a small script, which sh runs when it starts interactively, and adds the same script to /etc/bash.bashrc for bash. The script attaches to the claude session, so every shell the web terminal opens lands in Claude Code.
• The disk keeps the work. HOME is /data/home and the clone is /data/repo, both on a disk. Claude Code’s settings, conversation history and your uncommitted changes survive restarts and deployments. The tmux session and a task that’s running don’t: see What survives a restart or a deployment.
• GitHub is where work leaves the instance. Claude Code commits and pushes with a GitHub token that can reach one repository, and opens pull requests that you review and merge.

​

Before you begin

• A Sevalla company with a payment method. The S1 size needs one. See Pricing.
• A GitHub repository for Claude Code to work on, and a second, private one for this guide’s files, for example acme/claude-workspace.
• A Claude API key from the Claude Console, with a spend limit on its workspace. Or a Claude Pro, Max, Team or Enterprise plan and Claude Code on your computer, to create a token with claude setup-token.
• Git on your computer.

​

Create a GitHub token

• Repository access: only the repository Claude Code works on, for example acme/storefront.
• Repository permissions: Contents read and write, and Pull requests read and write. GitHub adds Metadata read-only by itself.
• Expiration: the shortest that suits you. When it expires, start.sh stops with gh: Bad credentials (HTTP 401) until you set a new token and deploy.

​

Create the project

mkdir claude-workspace && cd claude-workspace

FROM node:24-trixie-slim

# hadolint ignore=DL3008
RUN apt-get update \
  && apt-get install -y --no-install-recommends ca-certificates gh git jq less tini tmux \
  && rm -rf /var/lib/apt/lists/*

# Pinned, so a deployment never changes Claude Code under you. Update it on purpose.
ARG CLAUDE_CODE_VERSION=2.1.308
RUN npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION} \
  && npm cache clean --force

COPY managed-settings.json /etc/claude-code/managed-settings.json
COPY tmux.conf /etc/tmux.conf
COPY start.sh shell-init.sh /opt/claude/
RUN echo '. /opt/claude/shell-init.sh' >> /etc/bash.bashrc

# HOME is on the disk, so Claude Code's settings, sessions and your clone survive restarts.
# sh reads the file in ENV and bash reads /etc/bash.bashrc: both open into the tmux session.
ENV HOME=/data/home \
  SHELL=/bin/bash \
  ENV=/opt/claude/shell-init.sh \
  DISABLE_AUTOUPDATER=1

USER 1000:1000
WORKDIR /data
ENTRYPOINT ["tini", "--"]
CMD ["/opt/claude/start.sh"]

#!/bin/bash
set -euo pipefail

: "${GITHUB_REPO:?Set GITHUB_REPO to the repository to work on, as owner/name}"
: "${GH_TOKEN:?Set GH_TOKEN to a fine-grained GitHub token}"
if [ -z "${ANTHROPIC_API_KEY:-}${CLAUDE_CODE_OAUTH_TOKEN:-}" ]; then
  echo "Set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN" >&2
  exit 1
fi

# Answer Claude Code's first-run questions (theme, using the API key, trusting the
# repository), so the web terminal opens on a ready prompt.
mkdir -p "$HOME"
config=$HOME/.claude.json
[ -s "$config" ] || echo '{}' > "$config"
key=${ANTHROPIC_API_KEY:-}
jq --arg key "${key: -20}" '.hasCompletedOnboarding = true
  | .customApiKeyResponses.approved = ((.customApiKeyResponses.approved // []) + [$key] | unique)
  | .projects["/data/repo"].hasTrustDialogAccepted = true' "$config" > "$config.tmp"
mv "$config.tmp" "$config"

# git pushes with GH_TOKEN and commits as the token's GitHub user.
gh auth setup-git
login=$(gh api user --jq .login)
git config --global user.name "$login"
git config --global user.email "$(gh api user --jq .id)+$login@users.noreply.github.com"
[ -d /data/repo/.git ] || gh repo clone "$GITHUB_REPO" /data/repo

if ! tmux has-session -t claude 2>/dev/null; then
  # A shell runs in the session, so quitting Claude Code leaves a prompt to start it again.
  tmux new-session -d -s claude -c /data/repo
  tmux send-keys -t claude claude Enter
fi
echo "Claude Code is running in tmux. Open the Web terminal to join it."
exec sleep infinity

# Interactive shells source this file. Outside tmux, join Claude Code's session.
if [ -z "${TMUX:-}" ] && tmux has-session -t claude 2>/dev/null; then
  tmux attach -t claude
fi

set -g mouse on
set -g history-limit 50000

{
  "permissions": {
    "deny": [
      "Bash(git push --force*)",
      "Bash(git push -f *)",
      "Bash(gh pr merge *)",
      "Bash(gh repo delete *)"
    ],
    "disableBypassPermissionsMode": "disable"
  }
}

.git
.env*
Dockerfile
.dockerignore

chmod +x start.sh
git init
git add .
git commit -m "Run Claude Code on Sevalla"
git branch -M main
git remote add origin https://github.com/acme/claude-workspace.git
git push -u origin main

​

Deploy to Sevalla

​

Verify the deployment

1. On the Deployments tab, click the deployment. Its Build log shows 📦 Building and pushing docker image using Dockerfile... and ends with 🚀 Web has been deployed successfully., and its Dockerfile tab shows your Dockerfile.
2. Wait for the deployment’s status to change to Deployed. On the first start, the runtime logs show:
   Runtime logs

   Cloning into '/data/repo'...
   Claude Code is running in tmux. Open the Web terminal to join it.
   
3. Click the Web terminal tab. The terminal opens in Claude Code, ready for a task, with the model and /data/repo in its header and [claude] 0:claude* in tmux’s status bar at the bottom.

curl -s "https://api.sevalla.com/v3/applications/$APP_ID/deployments/$DEPLOYMENT_ID" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r .status

success

curl -s -X POST "https://api.sevalla.com/v3/applications/$APP_ID/processes/$WEB_ID/exec" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d '{"command": ["claude", "--version"]}'

{"stdout":"2.1.308 (Claude Code)\n","stderr":"","exit_code":0}

curl -s -X POST "https://api.sevalla.com/v3/applications/$APP_ID/processes/$WEB_ID/exec" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d '{"command": ["tmux", "list-sessions", "-F", "#{session_name}"]}'

{"stdout":"claude\n","stderr":"","exit_code":0}

​

Work with Claude Code

• Leave the session running. Close the browser tab, or press Ctrl-b then d to detach and get a plain shell in the same instance. Claude Code keeps working either way.
• Come back. Open the Web terminal tab again, from any browser. Every new tab or pane joins the same session; press Ctrl-b then d in it for a plain shell instead.
• From your own terminal. The Sevalla CLI opens the same session: sevalla apps processes terminal <web-process-id> --app-id <app-id>.
• Quit and restart Claude Code. /exit (or Ctrl-c twice) leaves a shell in the session. Run claude to start a new conversation, or claude --continue to pick up the last one.
• Work on another repository. The token reaches only the repositories you gave it. Add another one to the token, then clone it under /data from the session’s shell, for example gh repo clone acme/storefront-docs /data/storefront-docs, and start claude there. Claude Code asks once whether you trust the folder.

​

Choose the model

​

Use a Claude subscription

claude setup-token

​

Set permission rules

​

What survives a restart or a deployment

​

Choose the size and cost

​

Update Claude Code

​

Secure the session

• HTTP traffic stays off. Nothing on the internet reaches the instance. You reach it through the dashboard’s web terminal, the CLI or the API, all of which need your Sevalla account or an API key.
• Access to the application is access to the keys. Anyone who can open the application’s web terminal can use Claude Code with your keys and read them with printenv. Give access to the application with care. See Web terminal.
• Keys stay out of the image. The variables are available during runtime only, so they’re never in a build log or an image layer.
• The token is the boundary. One repository, contents and pull requests only, an expiry date, and a separate GitHub user if you want to see what Claude Code did. Set a spend limit on the Claude Console workspace of the API key.
• Read what you merge. Content Claude Code reads, such as issues, pull requests, web pages and dependencies, can contain instructions meant for it. Auto mode’s classifier checks each action, and you review every pull request before it reaches main.
• Outbound traffic is open. The instance can reach any address on the internet, as Claude Code needs to call the API and GitHub.

​

Troubleshoot

​

Deploy with the API

• An API key with the Company developer or Company admin role.
• This guide’s repository pushed as in Create the project, and its Git provider connected to your Sevalla user with access to the repository. Create application checks this: without access, it fails with 400 and Cannot access repository <repository URL>: Repository not found or you don't have access.
• Your Claude API key, the GitHub token, and curl and jq.

export SEVALLA_API_KEY=<your Sevalla API key> ANTHROPIC_API_KEY=<your Claude API key> GH_TOKEN=<your GitHub token>
API=https://api.sevalla.com/v3
REPO=https://github.com/acme/claude-workspace

curl -s "$API/resources/clusters" -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.[] | "\(.location)  \(.display_name)"'
CLUSTER_ID=$(curl -s "$API/resources/clusters" -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.[] | select(.location == "eu-frankfurt-1") | .id')

DISK_SIZE_ID=$(curl -s "$API/resources/disk-resource-types" -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.[] | select(.size_gib == 10) | .id')

APP_ID=$(curl -s -X POST "$API/applications" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg cluster "$CLUSTER_ID" --arg repo "$REPO" \
    '{display_name: "claude-workspace", cluster_id: $cluster, source: "privateGit", git_type: "github",
      repo_url: $repo, default_branch: "main"}')" \
  | jq -r .id)

curl -s -X PATCH "$API/applications/$APP_ID" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d '{"build_type": "dockerfile", "dockerfile_path": "Dockerfile", "docker_context": "."}' | jq -r .build_type

for pair in "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" "GH_TOKEN=$GH_TOKEN" "GITHUB_REPO=acme/storefront"; do
  curl -s -X POST "$API/applications/$APP_ID/env-vars" \
    -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
    -d "$(jq -n --arg key "${pair%%=*}" --arg value "${pair#*=}" \
      '{key: $key, value: $value, is_runtime: true, is_buildtime: false}')" | jq -r .key
done

WEB_ID=$(curl -s "$API/applications/$APP_ID/processes" -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.data[] | select(.type == "web") | .id')

curl -s -X PATCH "$API/applications/$APP_ID/processes/$WEB_ID" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d '{"is_ingress_enabled": false}' | jq -r .is_ingress_enabled

curl -s -X PUT "$API/applications/$APP_ID/processes/$WEB_ID/disk" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg size "$DISK_SIZE_ID" '{resource_type_id: $size, mount_path: "/data"}')" | jq -c .

DEPLOYMENT_ID=$(curl -s -X POST "$API/applications/$APP_ID/deployments" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" -d '{}' | jq -r .id)

for i in $(seq 1 120); do
  STATUS=$(curl -s "$API/applications/$APP_ID/deployments/$DEPLOYMENT_ID" \
    -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.status // empty')
  case $STATUS in success|failed|cancelled|skipped) break ;; esac
  sleep 15
done
echo "$STATUS"

curl -s "$API/applications/$APP_ID/runtime-logs?search=Claude%20Code%20is%20running" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.[].message'
curl -s -X POST "$API/applications/$APP_ID/processes/$WEB_ID/exec" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d '{"command": ["tmux", "list-sessions", "-F", "#{session_name}"]}' | jq -r .stdout