Skip to main content
Clone a repository, inspect changes, commit work, push a branch, or open a pull request from inside a box.

​
Configure Git Access

Pass a git config to Box.create to configure Git access. All fields are optional.
  • token — GitHub token. Required for private repositories, pushing, and creating pull requests.
  • userName — Git user name written to the container’s global git config on creation. Defaults to "Upstash Box".
  • userEmail — Git user email written to the container’s global git config on creation. Defaults to "box@upstash.com".
For a fine-grained token, the following permissions are sufficient for basic usage:
  • Contents — Read and write
  • Pull requests — Read and write
.env
UPSTASH_BOX_API_KEY=abx_xxxxxxxxxxxxxxxxxxxxxxxx
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxx

import { Box } from "@upstash/box"

const box = await Box.create({
  runtime: "node",
  git: {
    token: process.env.GITHUB_TOKEN,  // optional — required for private repos / push / PRs
    userName: "release-bot",          // optional — defaults to "Upstash Box"
    userEmail: "bot@acme.com",        // optional — defaults to "box@upstash.com"
  },
})

​
Quickstart

​
Clone a repository

await box.git.clone({
  repo: "https://github.com/acme/web-app",
  branch: "main",
})

await box.cd("web-app")

await box.git.exec({
  args: ["checkout", "-b", "fix/empty-state"],
})

​
Inspect what changed

Use status() for a compact summary and diff() to diff the repo’s uncommitted changes against the initial state. 
const status = await box.git.status()
const diff = await box.git.diff()

console.log(status)
console.log(diff)

​
Commit and push

After your code changes are ready, create a commit and push the branch. 
const commit = await box.git.commit({
  message: "fix: handle empty state in dashboard",
})

await box.git.push({ branch: "fix/empty-state" })

console.log(commit.sha)
console.log(commit.message)

​
Open a pull request

Create a PR once your branch is pushed. 
const pr = await box.git.createPR({
  title: "fix: handle empty state in dashboard",
  body: "Improves the dashboard empty state and avoids a broken loading flow.",
  base: "main",
})

console.log(pr.url)

​
API

​
Clone

Clones a repository into the current working directory in the box. 
await box.git.clone({
  repo: "https://github.com/acme/api",
})

// 👇 you can also select a branch during clone:
await box.git.clone({
  repo: "https://github.com/acme/api",
  branch: "develop",
})

​
Status

Returns the Git status output for the repository in the current working directory.
  • See what files changed
  • See if there are there untracked files
const status = await box.git.status()

​
Diff

Returns the current Git diff as a string.
  • Useful to display a patch in your UI
  • Review what an agent changed
const diff = await box.git.diff()

​
Commit

Creates a commit and returns commit information including the SHA and message. 
const commit = await box.git.commit({
  message: "feat: add onboarding checklist",
})
Use authorName and authorEmail to override the git identity for this commit only. If omitted, the identity configured on the box (via Box.create or updateConfig) is used. 
const commit = await box.git.commit({
  message: "feat: add onboarding checklist",
  authorName: "Alice",           // optional — overrides git identity for this commit only
  authorEmail: "alice@acme.com", // optional — overrides git identity for this commit only
})

​
Update Git Config

Updates the git identity (userName and/or userEmail) applied to the container. Partial updates are supported — you can update either field independently. At least one field is required. Returns the effective identity values after the update. If the box is running or idle, the new config is applied immediately inside the container. 
const config = await box.git.updateConfig({
  userName: "release-bot",
  userEmail: "release@acme.com",
})

console.log(config.git_user_name)  // "release-bot"
console.log(config.git_user_email) // "release@acme.com"

// 👇 partial update — change only one field
const config = await box.git.updateConfig({
  userEmail: "ci@acme.com",
})

​
Push

Pushes the current branch. You can also provide a branch name explicitly. 
// 👇 push to default branch
await box.git.push()

// 👇 or to a specific branch
await box.git.push({
  branch: "feature/onboarding-checklist",
})

​
Create a PR

Creates a pull request and returns the PR URL and metadata. 
const pr = await box.git.createPR({
  title: "feat: add onboarding checklist",
  body: "Adds a simple onboarding checklist to improve first-run guidance.",
  base: "main",
})

​
Checkout

Switches to another branch in the current repository. 
await box.git.checkout({
  branch: "release/v1.2.0",
})

​
Run a custom Git command

Runs a raw Git command and returns the command output. Useful escape hatch if the built-in helpers don’t cover a use case. 
const result = await box.git.exec({
  args: ["branch", "--show-current"],
})

​
Examples

​
Use Git with an agent

If you configured a box agent, it also has full git access. This is especially useful when the exact git steps are not known ahead of time. For example, if the user sends an open-ended request, you may not know in advance what branch name, commit message, or final push flow makes sense. In that case, you can let the agent inspect the repository, decide what changes are needed, and handle the git workflow itself. 
import { Box, Agent, ClaudeCode } from "@upstash/box"

const box = await Box.create({
  runtime: "node",
  agent: {
    provider: Agent.ClaudeCode,
    model: ClaudeCode.Opus_4_6,
    apiKey: process.env.ANTHROPIC_API_KEY,
  },
  git: {
    token: process.env.GITHUB_TOKEN,
  },
})

await box.git.clone({
  repo: "https://github.com/acme/web-app",
  branch: "main",
})

await box.cd("web-app")

const run = await box.agent.run({
  prompt: `
Inspect this repository and fix the broken mobile navigation.

Create a branch with a sensible name, make the necessary code and test changes, commit the changes, then push the branch and open a pull request against main.`,
})

​
End-to-end PR automation

import { Box, Agent, ClaudeCode } from "@upstash/box"

const box = await Box.create({
  runtime: "node",
  agent: {
    provider: Agent.ClaudeCode,
    model: ClaudeCode.Opus_4_6,
    apiKey: process.env.ANTHROPIC_API_KEY,
  },
  git: {
    token: process.env.GITHUB_TOKEN,
  },
})

await box.git.clone({
  repo: "https://github.com/acme/docs-site",
  branch: "main",
})

await box.cd("docs-site")

await box.git.exec({
  args: ["checkout", "-b", "docs/deployment-troubleshooting"],
})

await box.agent.run({
  prompt: "Add a troubleshooting section to the deployment guide.",
})

await box.git.commit({
  message: "docs: add deployment troubleshooting section",
})

await box.git.push({ branch: "docs/deployment-troubleshooting" })

const pr = await box.git.createPR({
  title: "docs: add deployment troubleshooting section",
  base: "main",
})