> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ppio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Git in a sandbox

> Clone, branch, commit, pull and push repositories inside a sandbox with the git helpers, including credentials, commit identity, remotes and config.

The SDK exposes `sandbox.git` helpers for common repository workflows: cloning, branching, committing, pulling, pushing, managing remotes, and configuring Git. Credentials can be passed inline to each operation, or stored once in the sandbox credential helper.

> [!NOTE]
>
> Install the SDK, or the CLI for `ppio` commands, and set the `PPIO_API_KEY` and `PPIO_DOMAIN` environment variables before running these examples. See [Quickstart](https://docs.ppio.ai/sandbox/quickstart.md) and [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

> [!WARNING]
>
> Credentials stored with `dangerouslyAuthenticate()` or `dangerously_authenticate()` are written to disk inside the sandbox and can be read by anything with sandbox access. Credentials kept in a remote URL with `dangerouslyStoreCredentials` or `dangerously_store_credentials` remain in the repository config and are readable by sandbox processes.

## Authenticate, clone, commit and push

**1. Authenticate to the Git server**

Store the credentials in the sandbox credential helper. This example targets a custom HTTPS server; without `host`, the credentials are stored for GitHub.

```python Python theme={null}
# Store the credentials in the sandbox credential helper.
sandbox.git.dangerously_authenticate(
    username=os.environ.get('GIT_USERNAME'),
    password=os.environ.get('GIT_TOKEN'),
    host='git.example.com',
    protocol='https',
)
```

```javascript Node.js theme={null}
// Store the credentials in the sandbox credential helper.
await sandbox.git.dangerouslyAuthenticate({
  username: process.env.GIT_USERNAME,
  password: process.env.GIT_TOKEN,
  host: 'git.example.com',
  protocol: 'https',
})
```

**2. Clone the repository**

```python Python theme={null}
# Clone the repository.
sandbox.git.clone('https://git.example.com/org/repo.git', path='/home/user/repo')
```

```javascript Node.js theme={null}
// Clone the repository.
await sandbox.git.clone('https://git.example.com/org/repo.git', { path: '/home/user/repo' })
```

**3. Stage and commit a change**

```python Python theme={null}
# Stage and commit a change.
sandbox.git.add('/home/user/repo', files=['README.md'])
sandbox.git.commit(
    '/home/user/repo',
    'Docs sync',
    author_name='PPIO Bot',
    author_email='bot@example.com',
)
```

```javascript Node.js theme={null}
// Stage and commit a change.
await sandbox.git.add('/home/user/repo', { files: ['README.md'] })
await sandbox.git.commit('/home/user/repo', 'Docs sync', {
  authorName: 'PPIO Bot',
  authorEmail: 'bot@example.com',
})
```

**4. Push to the upstream branch**

```python Python theme={null}
# Push to origin main and set it as the upstream.
sandbox.git.push('/home/user/repo', remote='origin', branch='main', set_upstream=True)
```

```javascript Node.js theme={null}
// Push to origin main and set it as the upstream.
await sandbox.git.push('/home/user/repo', {
  remote: 'origin',
  branch: 'main',
  setUpstream: true,
})
```

**5. Clean up**

```python Python theme={null}
sandbox.kill()
```

```javascript Node.js theme={null}
await sandbox.kill()
```

### Full example

```python Python theme={null}
import os
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

# Store the credentials in the sandbox credential helper.
sandbox.git.dangerously_authenticate(
    username=os.environ.get('GIT_USERNAME'),
    password=os.environ.get('GIT_TOKEN'),
    host='git.example.com',
    protocol='https',
)

# Clone the repository.
sandbox.git.clone('https://git.example.com/org/repo.git', path='/home/user/repo')

# Stage and commit a change.
sandbox.git.add('/home/user/repo', files=['README.md'])
sandbox.git.commit(
    '/home/user/repo',
    'Docs sync',
    author_name='PPIO Bot',
    author_email='bot@example.com',
)

# Push to origin main and set it as the upstream.
sandbox.git.push('/home/user/repo', remote='origin', branch='main', set_upstream=True)

sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

// Store the credentials in the sandbox credential helper.
await sandbox.git.dangerouslyAuthenticate({
  username: process.env.GIT_USERNAME,
  password: process.env.GIT_TOKEN,
  host: 'git.example.com',
  protocol: 'https',
})

// Clone the repository.
await sandbox.git.clone('https://git.example.com/org/repo.git', { path: '/home/user/repo' })

// Stage and commit a change.
await sandbox.git.add('/home/user/repo', { files: ['README.md'] })
await sandbox.git.commit('/home/user/repo', 'Docs sync', {
  authorName: 'PPIO Bot',
  authorEmail: 'bot@example.com',
})

// Push to origin main and set it as the upstream.
await sandbox.git.push('/home/user/repo', {
  remote: 'origin',
  branch: 'main',
  setUpstream: true,
})

await sandbox.kill()
```

## Inline credentials

For private HTTPS repositories, pass a username and password or token directly to operations such as `push`, `pull`, or `clone`.

```python Python theme={null}
import os
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

sandbox.git.push(
    '/home/user/repo',
    username=os.environ.get('GIT_USERNAME'),
    password=os.environ.get('GIT_TOKEN'),
)

sandbox.git.pull(
    '/home/user/repo',
    username=os.environ.get('GIT_USERNAME'),
    password=os.environ.get('GIT_TOKEN'),
)

sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

await sandbox.git.push('/home/user/repo', {
  username: process.env.GIT_USERNAME,
  password: process.env.GIT_TOKEN,
})

await sandbox.git.pull('/home/user/repo', {
  username: process.env.GIT_USERNAME,
  password: process.env.GIT_TOKEN,
})

await sandbox.kill()
```

## Store credentials with the credential helper

`dangerouslyAuthenticate()` or `dangerously_authenticate()` stores credentials inside the sandbox credential helper. Credentials are stored for GitHub by default, or for a custom HTTPS server when `host` is set.

> [!WARNING]
>
> Credentials are written to disk inside the sandbox and can be read by anything with sandbox access.

```python Python theme={null}
import os
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

sandbox.git.dangerously_authenticate(
    username=os.environ.get('GIT_USERNAME'),
    password=os.environ.get('GIT_TOKEN'),
)

sandbox.git.dangerously_authenticate(
    username=os.environ.get('GIT_USERNAME'),
    password=os.environ.get('GIT_TOKEN'),
    host='git.example.com',
    protocol='https',
)

sandbox.git.clone(
    'https://git.example.com/org/repo.git',
    path='/home/user/repo',
)

sandbox.git.push('/home/user/repo')

sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

await sandbox.git.dangerouslyAuthenticate({
  username: process.env.GIT_USERNAME,
  password: process.env.GIT_TOKEN,
})

await sandbox.git.dangerouslyAuthenticate({
  username: process.env.GIT_USERNAME,
  password: process.env.GIT_TOKEN,
  host: 'git.example.com',
  protocol: 'https',
})

await sandbox.git.clone('https://git.example.com/org/repo.git', {
  path: '/home/user/repo',
})

await sandbox.git.push('/home/user/repo')

await sandbox.kill()
```

## Keep credentials in the remote URL

By default, credentials are removed from the remote URL after clone. To retain them in `.git/config`, set `dangerouslyStoreCredentials: true` in Node.js or `dangerously_store_credentials=True` in Python.

> [!WARNING]
>
> Credentials kept in a remote URL remain in the repository config and are readable by sandbox processes.

```python Python theme={null}
import os
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

sandbox.git.clone(
    'https://git.example.com/org/repo.git',
    path='/home/user/repo',
    username=os.environ.get('GIT_USERNAME'),
    password=os.environ.get('GIT_TOKEN'),
)

sandbox.git.clone(
    'https://git.example.com/org/repo.git',
    path='/home/user/repo',
    username=os.environ.get('GIT_USERNAME'),
    password=os.environ.get('GIT_TOKEN'),
    dangerously_store_credentials=True,
)

sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

await sandbox.git.clone('https://git.example.com/org/repo.git', {
  path: '/home/user/repo',
  username: process.env.GIT_USERNAME,
  password: process.env.GIT_TOKEN,
})

await sandbox.git.clone('https://git.example.com/org/repo.git', {
  path: '/home/user/repo',
  username: process.env.GIT_USERNAME,
  password: process.env.GIT_TOKEN,
  dangerouslyStoreCredentials: true,
})

await sandbox.kill()
```

## Configure commit identity

`configureUser()` or `configure_user()` sets the commit author details globally, or locally for one repository.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

sandbox.git.configure_user('PPIO Bot', 'bot@example.com')

sandbox.git.configure_user(
    'PPIO Bot',
    'bot@example.com',
    scope='local',
    path='/home/user/repo',
)

sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

await sandbox.git.configureUser('PPIO Bot', 'bot@example.com')

await sandbox.git.configureUser('PPIO Bot', 'bot@example.com', {
  scope: 'local',
  path: '/home/user/repo',
})

await sandbox.kill()
```

## Clone a repository

Clone options include the destination path, branch selection, depth, username, password, and credential storage behavior.

> [tab] Python
>
> **path**
>
> Destination path.
>
> **branch**
>
> Branch to check out.
>
> **depth**
>
> Clone depth.
>
> **username**
>
> Username for HTTPS authentication.
>
> **password**
>
> Password or personal access token.
>
> **dangerously\_store\_credentials**
>
> Keep credentials in the remote URL.

> [tab] Node.js
>
> **path**
>
> Destination path.
>
> **branch**
>
> Branch to check out.
>
> **depth**
>
> Clone depth.
>
> **username**
>
> Username for HTTPS authentication.
>
> **password**
>
> Password or personal access token.
>
> **dangerouslyStoreCredentials**
>
> Keep credentials in the remote URL.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

sandbox.git.clone('https://git.example.com/org/repo.git', path='/home/user/repo')

sandbox.git.clone('https://git.example.com/org/repo.git', path='/home/user/repo', branch='main')

sandbox.git.clone('https://git.example.com/org/repo.git', path='/home/user/repo', depth=1)

sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

await sandbox.git.clone('https://git.example.com/org/repo.git', {
  path: '/home/user/repo',
})

await sandbox.git.clone('https://git.example.com/org/repo.git', {
  path: '/home/user/repo',
  branch: 'main',
})

await sandbox.git.clone('https://git.example.com/org/repo.git', {
  path: '/home/user/repo',
  depth: 1,
})

await sandbox.kill()
```

## Inspect and manage branches

`status()` reports the current branch, the ahead and behind counts, and the status of each file. `branches()` returns the branch list and the current branch.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

status = sandbox.git.status('/home/user/repo')
print(status.current_branch)
print(status.ahead)
print(status.behind)
print(status.file_status)

branches = sandbox.git.branches('/home/user/repo')
print(branches.current_branch)
print(branches.branches)

sandbox.git.create_branch('/home/user/repo', 'feature/new-docs')

sandbox.git.checkout_branch('/home/user/repo', 'main')

sandbox.git.delete_branch('/home/user/repo', 'feature/old-docs')

sandbox.git.delete_branch(
    '/home/user/repo',
    'feature/stale-docs',
    force=True,
)

sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

const status = await sandbox.git.status('/home/user/repo')
console.log(status.currentBranch)
console.log(status.ahead)
console.log(status.behind)
console.log(status.fileStatus)

const branches = await sandbox.git.branches('/home/user/repo')
console.log(branches.currentBranch)
console.log(branches.branches)

await sandbox.git.createBranch('/home/user/repo', 'feature/new-docs')

await sandbox.git.checkoutBranch('/home/user/repo', 'main')

await sandbox.git.deleteBranch('/home/user/repo', 'feature/old-docs')

await sandbox.git.deleteBranch('/home/user/repo', 'feature/stale-docs', {
  force: true,
})

await sandbox.kill()
```

## Stage and commit changes

`add` stages all changes or selected files. `commit` creates a commit, with options for the author name, author email, and empty commits.

> [tab] Python
>
> **files**
>
> Files to stage. Omit it to stage all changes.
>
> **author\_name**
>
> Author name for the commit.
>
> **author\_email**
>
> Author email for the commit.
>
> **allow\_empty**
>
> Create a commit with no staged changes.

> [tab] Node.js
>
> **files**
>
> Files to stage. Omit it to stage all changes.
>
> **authorName**
>
> Author name for the commit.
>
> **authorEmail**
>
> Author email for the commit.
>
> **allowEmpty**
>
> Create a commit with no staged changes.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

sandbox.git.add('/home/user/repo')

sandbox.git.commit('/home/user/repo', 'Initial commit')

sandbox.git.add(
    '/home/user/repo',
    files=['README.md', 'src/index.ts'],
)

sandbox.git.commit(
    '/home/user/repo',
    'Docs sync',
    author_name='PPIO Bot',
    author_email='bot@example.com',
    allow_empty=True,
)

sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

await sandbox.git.add('/home/user/repo')

await sandbox.git.commit('/home/user/repo', 'Initial commit')

await sandbox.git.add('/home/user/repo', {
  files: ['README.md', 'src/index.ts'],
})

await sandbox.git.commit('/home/user/repo', 'Docs sync', {
  authorName: 'PPIO Bot',
  authorEmail: 'bot@example.com',
  allowEmpty: true,
})

await sandbox.kill()
```

## Pull and push

`push` and `pull` use the configured upstream by default. A remote, a branch, and upstream configuration can also be set per call.

> [tab] Python
>
> **remote**
>
> Remote to push to or pull from.
>
> **branch**
>
> Branch to push to or pull from.
>
> **set\_upstream**
>
> Set the pushed branch as the upstream.

> [tab] Node.js
>
> **remote**
>
> Remote to push to or pull from.
>
> **branch**
>
> Branch to push to or pull from.
>
> **setUpstream**
>
> Set the pushed branch as the upstream.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

sandbox.git.push('/home/user/repo')

sandbox.git.pull('/home/user/repo')

sandbox.git.push(
    '/home/user/repo',
    remote='origin',
    branch='main',
    set_upstream=True,
)

sandbox.git.pull(
    '/home/user/repo',
    remote='origin',
    branch='main',
)

sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

await sandbox.git.push('/home/user/repo')

await sandbox.git.pull('/home/user/repo')

await sandbox.git.push('/home/user/repo', {
  remote: 'origin',
  branch: 'main',
  setUpstream: true,
})

await sandbox.git.pull('/home/user/repo', {
  remote: 'origin',
  branch: 'main',
})

await sandbox.kill()
```

## Manage remotes and configuration

`remoteAdd()` or `remote_add()` adds a remote, optionally fetches after adding, or overwrites an existing remote. `setConfig()` and `getConfig()`, or `set_config()` and `get_config()`, manage Git settings globally or per repository.

`remote_add()` / `remoteAdd()` options:

**fetch**

Fetch after adding the remote.

**overwrite**

Overwrite an existing remote with the same name.

`set_config()` / `get_config()` options:

**scope**

Apply the setting globally or to one repository.

**path**

Repository path for a local setting.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

sandbox.git.remote_add('/home/user/repo', 'origin', 'https://git.example.com/org/repo.git')

sandbox.git.remote_add(
    '/home/user/repo',
    'origin',
    'https://git.example.com/org/repo.git',
    fetch=True,
)

sandbox.git.remote_add(
    '/home/user/repo',
    'origin',
    'https://git.example.com/org/repo.git',
    overwrite=True,
)

sandbox.git.set_config('pull.rebase', 'false')

value = sandbox.git.get_config('pull.rebase')

sandbox.git.set_config(
    'pull.rebase',
    'false',
    scope='local',
    path='/home/user/repo',
)

local_value = sandbox.git.get_config(
    'pull.rebase',
    scope='local',
    path='/home/user/repo',
)

sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

await sandbox.git.remoteAdd('/home/user/repo', 'origin', 'https://git.example.com/org/repo.git')

await sandbox.git.remoteAdd('/home/user/repo', 'origin', 'https://git.example.com/org/repo.git', {
  fetch: true,
})

await sandbox.git.remoteAdd('/home/user/repo', 'origin', 'https://git.example.com/org/repo.git', {
  overwrite: true,
})

await sandbox.git.setConfig('pull.rebase', 'false')

const value = await sandbox.git.getConfig('pull.rebase')

await sandbox.git.setConfig('pull.rebase', 'false', {
  scope: 'local',
  path: '/home/user/repo',
})

const localValue = await sandbox.git.getConfig('pull.rebase', {
  scope: 'local',
  path: '/home/user/repo',
})

await sandbox.kill()
```


## Related topics

- [Run a desktop sandbox for computer use](https://docs.ppio.ai/sandbox/computer-use.md)
- [Agent Sandbox: secure cloud sandboxes for AI agents](https://docs.ppio.ai/sandbox/overview.md)
- [Mount an S3 bucket in a sandbox](https://docs.ppio.ai/sandbox/filesystem/mount-s3.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.