README.md

---
title: claude-code-job
emoji: 🤖
colorFrom: gray
colorTo: yellow
sdk: docker
app_port: 7860
pinned: false
---

# claude-code-job

A Docker image with [Claude Code](https://claude.com/claude-code) preinstalled, meant to be used as
an image for [HF Jobs](https://huggingface.co/docs/huggingface_hub/guides/jobs) — so agent tasks run
on Hugging Face infrastructure instead of your laptop.

This Space is **not an app**. It only exists so that HF builds and hosts the image; the default
`CMD` just serves a placeholder page to keep the Space healthy. The Space can be paused — jobs will
still pull the built image.

## What's in it

- `claude` (Claude Code, pinned version) running as the non-root `node` user (uid 1000)
- Permissions bypassed by default via `~/.claude/settings.json`, so no prompt ever blocks a job
- `hf` CLI, `git`, `ripgrep`, `jq`, `python3`
- `/workspace` as the working directory, writable by `node`

### Why non-root

`--dangerously-skip-permissions` is refused when Claude Code runs as root. The image therefore runs
as `node`, and sets the config equivalent instead:

```json
{ "permissions": { "defaultMode": "bypassPermissions" } }
```

Using the config rather than the CLI flag means *any* invocation gets the bypass — including a bare
`claude -p`, or the Agent SDK — without every caller having to remember the flag.

## Usage

Claude Code needs credentials. Create a long-lived token with `claude setup-token`, put it in a
file, and pass it as a job secret so it never appears in the job spec or logs:

```bash
# secrets.env  ->  CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
hf jobs run --flavor cpu-basic --secrets-file secrets.env \
  hf.co/spaces/Wauplin/claude-code-job \
  claude -p "who are you?"
```

An `ANTHROPIC_API_KEY=...` in that file works too, if you'd rather bill per token than against a
subscription.

### Giving the agent Hub access

Add `HF_TOKEN=hf_...` to the secrets file and the agent can use the `hf` CLI to read and write the
Hub — clone a repo, open a PR, upload results to a bucket:

```bash
hf jobs run --flavor cpu-basic --secrets-file secrets.env \
  hf.co/spaces/Wauplin/claude-code-job \
  bash -c 'git clone https://huggingface.co/datasets/me/notes /workspace/notes \
           && claude -p "summarise the notes in /workspace/notes into SUMMARY.md"'
```

### Caveats

- Jobs have a **30 minute default timeout**; pass `--timeout 2h` for longer agent runs.
- Bypassing permissions means the agent runs commands unreviewed. Keep the blast radius to the
  job container and scope the tokens you hand it.

## Building locally

```bash
docker build -t claude-code-job .
docker run --rm --env-file secrets.env claude-code-job claude -p "who are you?"
```