# Recreate

`POST /workspaces/:workspace/sandboxes/:sandbox_id/recreate`

Recreate a sandbox: wipe its disk and run the setup commands again

**Required Scopes:** `SANDBOX_WRITE`

## URL Parameters

```typescript
interface URLParameters {
  /** The human-readable ID of the workspace */
  workspace: string; // Example: "my-company"
  /** The ID of the sandbox */
  sandbox_id: string; // Example: "sb-1234567890abcdef"
}
```

## Response Body

```typescript
interface ResponseBody {
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** The ID of the sandbox */
  id?: string;
  /** A human-readable ID. Alphanumeric characters, underscores, and hyphens (hyphens cannot appear at the start or end). */
  identifier?: string;
  /** The name of the sandbox */
  name?: string;
  /** The current status of the sandbox */
  status?: "STARTING" | "STOPPING" | "FAILED" | "RUNNING" | "STOPPED" | "RESTORING";
  /** The current setup status of the sandbox */
  setup_status?: "INPROGRESS" | "SUCCESS" | "FAILED" | "STALE";
  /** The operating system of the sandbox ["ubuntu:22.04", "ubuntu:24.04"] */
  os?: string;
  /** The resource configuration of the sandbox (CPU x RAM) */
  resources?: "1x2" | "2x4" | "3x6" | "4x8" | "5x10" | "6x12" | "7x14" | "8x16" | "9x18" | "10x20" | "11x22" | "12x24" | "CUSTOM";
  /** The commands to run during first boot of the sandbox */
  first_boot_commands?: string;
  /** The application directory of the sandbox */
  app_dir?: string;
  /** The list of apps (run commands) for the sandbox */
  apps?: SandboxAppView[];
  /** The list of items (repositories and artifacts) to fetch into the sandbox */
  fetch?: SandboxFetchView[];
  /** The timeout in seconds after which the sandbox will be automatically stopped */
  timeout?: number;
  /** The list of tags associated with the sandbox */
  tags?: string[];
  /** The boot logs of the sandbox */
  boot_logs?: string[];
  /** The tunnel endpoints of the sandbox */
  endpoints?: TunnelView[];
  /** The SSH hostname */
  ssh_host?: string;
  /** The SSH port */
  ssh_port?: number;
  /** The scope of the sandbox: PROJECT, ENVIRONMENT, or WORKSPACE */
  scope?: "PROJECT" | "ENVIRONMENT" | "WORKSPACE";
  project?: ProjectView;
  environment?: ShortEnvironmentView;
  /** Access permissions configuration */
  permissions?: PermissionsView;
  /** Note for this resource */
  note?: string;
  /** YAML note for AI agents operating on this resource */
  agent_note?: string;
  /** Sandbox creation date */
  create_date?: string;
  /** The environment variables of the sandbox */
  variables?: EnvironmentVariableView[];
}
```

## Type Definitions

```typescript
interface SandboxAppView {
  /** The auto-generated ID of the app */
  id?: string;
  /** The run command of the app */
  command?: string;
  /** The current status of the app */
  app_status?: "NONE" | "RUNNING" | "ENDED" | "FAILED";
}

interface SandboxFetchView {
  /** The type of the fetch item: PROJECT_REPO, PUBLIC_REPO, or ARTIFACT */
  type?: "PROJECT_REPO" | "PUBLIC_REPO" | "ARTIFACT";
  /** The URL of the git repository (for PUBLIC_REPO type) */
  repository?: string;
  /** The branch, tag, or commit to checkout. Defaults to the default branch */
  ref?: string;
  /** The target path where the item will be cloned/downloaded. Defaults to the app directory */
  path?: string;
  /** The command to run after fetching */
  build_command?: string;
  /** The artifact identifier in format pkg:version (for ARTIFACT type) */
  artifact?: string;
}

interface TunnelView {
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** The name of the tunnel */
  name: string;
  /** The endpoint URL of the tunnel */
  endpoint: string;
  /** The type of the tunnel */
  type: "TCP" | "TLS" | "HTTP" | "SSH";
  /** The region the tunnel is exposed from. When not set, the region of the agent is used */
  region?: "US" | "EU" | "AS";
  /** The IP addresses or domains allowed to access the tunnel */
  whitelist?: string[];
  /** The connection timeout of the tunnel in seconds */
  timeout?: number;
  /** The HTTP-specific settings of the tunnel */
  http?: HttpSettingsView;
  /** The TLS/SSL encryption settings of the tunnel */
  tls?: TlsSettingsView;
  /** The url of the tunnel */
  endpoint_url?: string;
  /** Whether the tunnel is connected to the edge (tunnel is established) */
  active?: boolean;
  /** Latency to the target in milliseconds. When >= 0 the target is reachable */
  target_latency?: number;
}

interface HttpSettingsView {
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** Whether to verify SSL/TLS certificates */
  verify_certificate?: boolean;
  /** Enable HTTP compression */
  compression?: boolean;
  /** Enable HTTP/2 protocol support */
  http2?: boolean;
  /** Log incoming HTTP requests */
  log_requests?: boolean;
  /** Custom HTTP headers to add to requests */
  request_headers?: object;
  /** List of allowed User-Agent strings */
  whitelist_user_agents?: string[];
  /** Rewrite the Host header to this value */
  rewrite_host_header?: string;
  /** Custom HTTP headers to add to responses */
  response_headers?: object;
  /** Basic authentication username */
  login?: string;
  /** Basic authentication password */
  password?: string;
  /** Custom TLS Certificate Authority */
  tls_ca?: string;
  /** Circuit breaker threshold (number of failed requests) */
  circuit_breaker?: number;
  /** Base path for serving requests */
  serve_path?: string;
  /** Type of authentication used */
  auth_type?: "NONE" | "BASIC" | "BUDDY";
}

interface TlsSettingsView {
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** Private key for TLS certificate */
  private_key?: string;
  /** TLS certificate */
  certificate?: string;
  /** Certificate Authority certificate */
  ca_certificate?: string;
  /** Where to terminate TLS connection. Default: `REGION` */
  terminate_at?: "REGION" | "AGENT" | "TARGET";
}

interface ProjectView {
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** The human-readable ID of the project */
  name?: string;
  /** The Name of the project */
  display_name: string;
  /** The status of the project */
  status?: string;
  /** Indicates if this is a public project */
  access?: "PRIVATE" | "PUBLIC";
  /** The creation date of the project */
  create_date?: string;
  /** Repo slug of the Bitbucket, GitHub or GitLab project the project is synchronized with; null for Buddy and custom repository projects */
  external_project_id?: string;
  /** ID of the project in GitLab. If unset, it is resolved from `external_project_id`. If set, it must point to the same GitLab project as `external_project_id` */
  git_lab_project_id?: number;
  /** SSH or HTTPS url of the git repository. Required when adding the project integrated with custom git repository */
  custom_repo_url?: string;
  /** Username used to authorize access to the git repository. Required when adding the project integrated with custom git repository */
  custom_repo_user?: string;
  /** Password used to authorize access to the git repository. Required when adding the project integrated with custom git repository and the provided `custom_repo_url` is the HTTPS url */
  custom_repo_pass?: string;
  /** The ID of the private SSH key used to authorize access to the git repository. Used when adding the project integrated with private git server by SSH url. If unset, the workspace SSH key is used */
  custom_repo_ssh_key_id?: number;
  /** User/member reference */
  created_by?: MemberView;
  /** The HTTP repository URL */
  http_repository?: string;
  /** The SSH repository URL */
  ssh_repository?: string;
  /** The default branch name */
  default_branch?: string;
  /** Integration reference */
  integration?: IntegrationIdView;
  /** Defines whether the submodules are fetched during the runs in this project */
  fetch_submodules?: boolean;
  /** Name of the key that will be used to authorize while fetching the submodules. Required when `fetch_submodules` is set to `true` */
  fetch_submodules_env_key?: string;
  /** Enables/disables pull requests in the project. Available only for projects synchronized with GitHub or GitHub Enterprise repository */
  allow_pull_requests?: boolean;
  /** If set to true, the default branch will be updated from GitHub/GitLab/Bitbucket. */
  update_default_branch_from_external?: boolean;
  /** If set to true, the project is created without any repository attached. */
  without_repository?: boolean;
}

interface MemberView {
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** The ID of the user */
  id?: number;
  /** The name of the user */
  name?: string;
  /** The avatar URL of the user */
  avatar_url?: string;
  /** The email address of the user */
  email?: string;
  /** Whether the user has admin privileges */
  admin?: boolean;
  /** Whether the user is workspace owner */
  workspace_owner?: boolean;
}

interface IntegrationIdView {
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** A human-readable ID of the integration */
  identifier?: string;
  /** The unique hash ID of the integration */
  hash_id?: string;
  /** The name of the integration */
  name?: string;
  /** The type of integration */
  type?: "GIT_HUB" | "BITBUCKET" | "GOOGLE" | "DIGITAL_OCEAN" | "SLACK" | "MODULUS" | "HEROKU" | "AMAZON" | "GIT_LAB" | "SHOPIFY" | "GIT_HUB_ENTERPRISE" | "GIT_LAB_ENTERPRISE" | "PUSHOVER" | "PUSHBULLET" | "RACKSPACE" | "CUSTOM" | "CLOUDFLARE" | "NEW_RELIC" | "SENTRY" | "ROLLBAR" | "DATADOG" | "DO_SPACES" | "HONEYBADGER" | "VULTR" | "SENTRY_ENTERPRISE" | "LOGGLY" | "HIP_CHAT" | "FIREBASE" | "TELEGRAM" | "AZURE" | "UPCLOUD" | "GHOST_INSPECTOR" | "NETLIFY" | "AZURE_CLOUD" | "MICROSOFT_TEAMS" | "GOOGLE_SERVICE_ACCOUNT" | "GOOGLE_PLAY_STORE" | "DOCKER_HUB" | "APP_STORE" | "GIT_HUB_APP" | "GIT_HUB_APP_ENTERPRISE" | "GIT_HUB_API" | "ATOP" | "SNYK" | "STACK_HAWK" | "BLACKFIRE" | "BACKBLAZE" | "ONE_LOGIN" | "OKTA" | "CONTENTFUL" | "JIRA" | "NPM_REGISTRY" | "ANTHROPIC" | "GOOGLE_GEMINI" | "OPEN_AI" | "CURSOR" | "OPENCODE" | "CLICKUP" | "GROK";
  /** The authentication method used by the integration */
  auth_type?: "OAUTH" | "TOKEN" | "API_KEY" | "APP" | "APP_SPRYKER" | "TOKEN_APP_EXTENSION" | "DEFAULT" | "OIDC" | "TRUSTED" | "APP_RW";
  /** The host URL for custom integrations */
  host_url?: string;
  /** The webhook URL for receiving notifications */
  webhook_address?: string;
  /** The ATOP service URL */
  atop_url?: string;
  /** The application ID for Azure Cloud integrations */
  app_id?: string;
  /** The Google Cloud project ID */
  google_project?: string;
  /** The JWT audience for token validation */
  audience?: string;
}

interface ShortEnvironmentView {
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** The ID of the environment */
  id?: string;
  /** The name of the environment */
  name?: string;
  /** A human-readable ID of the environment. Alphanumeric characters, underscores, and hyphens (hyphens cannot appear at the start or end). */
  identifier?: string;
  /** The list of tags associated with the environment */
  tags?: string[];
  /** The scope of the environment */
  scope?: "PROJECT" | "WORKSPACE";
}

interface PermissionsView {
  /** Access level for other workspace members */
  others?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
  /** List of specific users with their access levels */
  users?: UserPermissionView[];
  /** List of user groups with their access levels */
  groups?: GroupPermissionView[];
}

interface UserPermissionView {
  /** The ID of the user */
  id?: number;
  /** The access level for the user */
  access_level?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
}

interface GroupPermissionView {
  /** The ID of the group */
  id?: number;
  /** The access level for the group */
  access_level?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
}

interface EnvironmentVariableView {
  /** The ID of the variable */
  id?: number;
  /** The name of the variable */
  key?: string;
  /** The value of the variable */
  value?: string;
  /** The type of the added variable */
  type?: "VAR" | "FILE" | "SSH_KEY" | "IOS_KEYCHAIN" | "IOS_PROVISION_PROFILES" | "SSH_PUBLIC_KEY" | "GPG_KEY";
  /** If set to `true` the variable value will be encrypted and hidden */
  encrypted?: boolean;
  /** If set to `true` the variable value can be set by Buddy actions */
  settable?: boolean;
  /** Available only if `type=VAR`. If set to `true` the variable value can be set by Buddy actions only for execution time */
  run_only_settable?: boolean;
  /** Initial path for the variable */
  init_path?: string;
  /** Default value for the variable */
  defaults?: string;
  /** Specifies where to copy the file on each run. Set if `type` is `FILE`, `SSH_KEY`, `SSH_PUBLIC_KEY`, `IOS_KEYCHAIN`, or `IOS_PROVISION_PROFILES` */
  file_path?: string;
  /** File permission set on copy to a container on each run. Set if `type` is `FILE`, `SSH_KEY`, `SSH_PUBLIC_KEY`, `IOS_KEYCHAIN`, or `IOS_PROVISION_PROFILES` */
  file_chmod?: string;
  /** Set if `type` is `FILE`, `SSH_KEY`, `SSH_PUBLIC_KEY`, `IOS_KEYCHAIN`, or `IOS_PROVISION_PROFILES`. If it's `NONE`, the variable can be used as a parameter in an action. For `CONTAINER`, the given key is additionally copied to an action container on each run */
  file_place?: "NONE" | "CONTAINER";
  /** Whether the file is binary */
  binary?: boolean;
  /** Public value for SSH key type variables */
  public_value?: string;
  /** Fingerprint of SSH key */
  key_fingerprint?: string;
  /** Checksum of the variable value */
  checksum?: string;
  /** Password for certificates */
  password?: string;
  /** Passphrase for encrypted SSH keys */
  passphrase?: string;
  /** Key identifier for iOS certificates, provisioning profiles, or GPG keys */
  key_identifier?: string;
  /** Set to `true` to disable the variable. Disabled variables are not injected anywhere */
  disabled?: boolean;
  /** Note for this resource */
  note?: string;
  /** YAML note for AI agents operating on this resource */
  agent_note?: string;
}

```

## Response Example

**Status:** `200 OK`

```json
{
  "url": "https://api.buddy.works/workspaces/my-workspace/sandboxes/sb-12345",
  "html_url": "https://app.buddy.works/sandboxes/sb-12345",
  "id": "sb-12345",
  "identifier": "my-api-sandbox",
  "name": "My API Development Sandbox",
  "status": "RUNNING",
  "source_sandbox_id": null,
  "snapshot_id": null,
  "os": "ubuntu:24.04",
  "resources": "2x4",
  "first_boot_commands": "npm install && npm run build",
  "app_dir": "/app",
  "apps": [
    {
      "id": "a1b2c3d",
      "command": "npm start",
      "app_status": "RUNNING"
    }
  ],
  "timeout": 3600,
  "tags": [
    "development",
    "api",
    "nodejs"
  ],
  "boot_logs": [
    "Starting sandbox...",
    "Installing dependencies...",
    "npm install completed successfully",
    "Building application...",
    "Application ready on port 3000"
  ],
  "setup_status": "SUCCESS",
  "endpoints": [
    {
      "name": "www",
      "endpoint": "80",
      "type": "HTTP",
      "region": "EU",
      "whitelist": [
        "192.168.1.0/24"
      ],
      "timeout": 30,
      "active": true,
      "target_latency": 12,
      "http": {
        "endpoint_url": "https://www-my-api-sandbox-proj1757492386363-my-workspace.eu-1.buddy.app",
        "verify_certificate": true,
        "compression": true,
        "http2": true,
        "log_requests": true,
        "request_headers": {
          "X-Forwarded-For": "wp.pl"
        },
        "response_headers": {
          "X-Frame-Options": "DENY"
        },
        "circuit_breaker": 5,
        "serve_path": "/api"
      }
    }
  ],
  "project": {
    "url": "https://api.buddy.works/workspaces/my-workspace/projects/proj1757492386363",
    "html_url": "https://app.buddy.works/proj1757492386363",
    "name": "proj1757492386363",
    "display_name": "proj1757492386363",
    "status": "ACTIVE"
  },
  "variables": [
    {
      "key": "my_var",
      "value": "some_value",
      "type": "VAR",
      "description": "a sandbox variable"
    }
  ],
  "permissions": {
    "others": "READ_ONLY",
    "users": [
      {
        "id": 42,
        "access_level": "READ_WRITE"
      }
    ],
    "groups": [
      {
        "id": 10,
        "access_level": "READ_WRITE"
      }
    ]
  },
  "note": "Notes about this resource",
  "agent_note": "my_custom_field: note for agent"
}
```

---
Original source: https://buddy.works/docs/api/sandboxes/recreate