Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

Lookup tables for Copy & Sync. The Copy & Sync API page carries the full request and response schemas.

POST /api/v1/computers/{id}/copy, where {id} is the source computer.

Auth tokens need computers.read and computers.create. If the source has AI enabled, the token also needs computers.features.ai. If it has Hoody Kit enabled, the token also needs computers.features.hoody_kit. The copy inherits those feature settings.

FieldRequiredMeaning
target_project_idYesDestination project
target_server_idNoDestination server. Defaults to the source server
nameNoCopy name. Auto-generated if omitted
ssh_public_keyNoSSH public key for the copy. The copy never inherits the source’s key. Omit it and the copy has no SSH access until you add a key. A key already on another computer is refused with 409 SSH_PUBLIC_KEY_IN_USE, an unparsable key with 400. An auth token needs resources.ssh_keys to send it
source_snapshotNoSpecific snapshot to copy from, by its name. Copies the latest state if omitted. An auth token needs computers.features.snapshots to use it
copy_firewall_rulesNoCopy the source’s firewall rules (ACL) to the copy. Default: false. An auth token needs resources.firewalls to use it
copy_network_rulesNoCopy the source’s network rules and settings to the copy. Default: false. An auth token needs computers.features.networking to use it
kvmNoAsk for /dev/kvm on the copy so it can run full VMs. Default: false, and the copy never inherits the source’s KVM grant. With true: an auth token needs computers.features.kvm (else 403); a free-tier or subserver target is refused with 403, an unsized target with 400. On a dedicated (bare-metal) server the copy is created with kvm: false and the response carries a kvm_note: enable KVM with hoody computers kvm enable -c "$COPY_ID" (or PUT /api/v1/computers/{id}/kvm) once the copy is stopped, then start it. See Virtual Machines
dev_kvmNoAccepted alias of kvm on input. If both are sent they must agree, and kvm wins

CLI: hoody computers copy <id> --target-project … [--target-server-id …] [--name …] [--ssh-public-key …] [--source-snapshot …] [--copy-firewall-rules] [--copy-network-rules] [--kvm], plus --until-done to wait for the result (exit 0 done, 1 failed, 124 timed out) and --timeout to stop waiting after a duration (default 10m).

The copy answers 201 while it runs in the background:

{
"statusCode": 201,
"message": "Computer copy initiated successfully",
"data": {
"id": "01bcdef123456789abcdef01",
"name": "computer-copy",
"status": "copying",
"source_computer_id": "890abcdef12345678901cdef",
"project_id": "67e89abc123def456789abcd",
"server_id": "63f8b0e5c9a1b2d3e4f5a6b7",
"server_name": "node-us",
"copy_firewall_rules": false,
"copy_network_rules": false,
"operation_id": "9f86d081884c7d659a2feaa0c55ad015",
"created_at": "2025-11-09T15:00:00.000Z"
}
}
StatusMeaning
copyingThe copy is in progress. Check again for its final status
runningThe copy is done and started automatically
stoppedOnly when the copy was made with copy_network_rules: true: the copied computer was left stopped because network setup or automatic startup could not complete. Check its network configuration and reported error before starting it
failedThe copy failed and cannot be started. Delete it and copy again

operation_id, when present, identifies the copy operation: the computer.operation.completed or computer.operation.failed event that reports the outcome carries the same value (Copy & Sync API page). The response also echoes copy_firewall_rules and copy_network_rules.

source_computer_id is the only copy-relationship field: a copy has no separate history ID. When the source is deleted, its copies keep running and their source_computer_id becomes null, so record which copies came from a source before you delete it if you need that history. The computers list comes in pages of 50 by default, at most 100. To find every copy of a source, filter all pages, not the first. Expired and deleting computers are left out unless you ask for them: pass --include-expired --include-deleting to hoody computers list, or include_expired and include_deleting set to true to the SDK and HTTP calls. The SDK’s listAll() follows the pages but stops with an error after 1,000 pages; with limit: 100 that is 100,000 computers. hoody computers list fetches pages automatically up to 10,000 items and reports truncation on stderr. For a search beyond those limits, use the HTTP pagination loop below, which requests each page until totalPages:

const all = await client.api.computers.listAll({ limit: 100, include_expired: true, include_deleting: true });
const copies = all.filter((c) => c.source_computer_id === SOURCE_ID);
Terminal window
set -eo pipefail
PAGE=1
while true; do
RESP=$(curl -sf "https://api.hoody.com/api/v1/computers?page=$PAGE&limit=100&include_expired=true&include_deleting=true" \
-H "Authorization: Bearer $HOODY_TOKEN")
echo "$RESP" | jq -r --arg src "$SOURCE_ID" '.data.computers[] | select(.source_computer_id == $src) | .id'
[ "$PAGE" -ge "$(echo "$RESP" | jq -r '.data.pagination.totalPages')" ] && break
PAGE=$((PAGE + 1))
done

POST /api/v1/computers/{id}/sync (hoody computers sync <id>, client.api.computers.sync(id)) does not sync. The usual checks answer first:

StatusWhenWhat to do
404Unknown computerCheck the ID
403You lack permissionAsk for access
409 COMPUTER_NOT_COPIEDThe computer has no source_computer_id (check with GET /api/v1/computers/{computer_id})Sync applies only when a source is recorded
404The recorded source computer cannot be foundCheck the source; the copy remains independent
409The copy or its source is in a state that cannot be syncedCheck the status of both computers
409 COMPUTER_SYNC_UNAVAILABLEEvery other request: syncing a copy is not available yet. The copy is left as it wasCopy the source again (how)
{
"statusCode": 409,
"error": "COMPUTER_SYNC_UNAVAILABLE",
"message": "Syncing a copy is not available yet. To get the source's latest files, copy the source again."
}
Computer sizeSame serverCross-server (data transfer over network)
10 GB~1-2 minutes~3-5 minutes
50 GB~3-5 minutes~10-15 minutes
100 GB~5-10 minutes~20-30 minutes

Times depend on computer size, network bandwidth between servers, server load and snapshot size. Under 10 GB, a same-server copy usually finishes in one to two minutes; cross-server times scale with network bandwidth.

Copy and sync requests share an account-wide write limit, by default 10 requests per 5 minutes and 20 per hour, counted across both endpoints. A request over either limit returns 429 with a Retry-After header and starts nothing, so wait and retry it. Fan out in bounded batches instead of firing one request per copy at once.

The source and destination projects must belong to your account. Create a project in your account for each developer, then copy the template into it.

// Copy a template into one project in your account per developer
async function copyTeamEnvironments(templateId, teamProjects) {
const token = process.env.HOODY_TOKEN;
const headers = {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
};
const BATCH_SIZE = 5;
async function copyOne({ projectId, name }, attempt = 1) {
const response = await fetch(`https://api.hoody.com/api/v1/computers/${templateId}/copy`, {
method: 'POST',
headers,
body: JSON.stringify({ target_project_id: projectId, name })
});
if (response.status === 429 && attempt <= 5) {
// Respect the account-wide copy limit
const retryAfter = Number(response.headers.get('retry-after')) || 30;
await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
return copyOne({ projectId, name }, attempt + 1);
}
const result = await response.json();
if (!response.ok) {
console.error(`Copy failed for ${name}:`, result.message);
return null;
}
return result;
}
// Copy in bounded batches, never all at once
const copies = [];
for (let i = 0; i < teamProjects.length; i += BATCH_SIZE) {
const batch = teamProjects.slice(i, i + BATCH_SIZE);
copies.push(...await Promise.all(batch.map(entry => copyOne(entry))));
}
console.log(`Created ${copies.filter(Boolean).length} team environments`);
}
copyTeamEnvironments('template_computer_id', [
{ projectId: 'alice_project_id', name: 'alice-dev-env' },
{ projectId: 'bob_project_id', name: 'bob-dev-env' },
{ projectId: 'charlie_project_id', name: 'charlie-dev-env' }
]);

The whole team starts on the same tools and configuration.

Each recipe is a copy request from the guide with different targets. A copy holds its source’s state at the time of the copy; to move later changes along, copy again and delete the old copy.

Get the exact production state for testing. Staging then matches production: same code, same data, same configuration. Firewall and network rules are copied only when you ask for them. Test updates there before deploying to production.

Terminal window
set -eo pipefail
# Create staging from production
hoody computers copy "$PROD_ID" --target-project "$STAGING_PROJECT" --name staging-api
# After a production deployment: copy production again and wait for it
# (exits 1 if the copy fails, which keeps the old staging copy)
NEW_STAGING_ID=$(hoody computers copy "$PROD_ID" --target-project "$STAGING_PROJECT" \
--until-done -o json | jq -er '.response.id')
# The copy can finish with the new computer stopped: check that it is running.
# If it is stopped or failed, keep the old staging copy and fix the problem first.
[ "$(hoody computers get "$NEW_STAGING_ID" -o json | jq -r '.status')" = "running" ]
# The new staging copy is running: delete the old one
hoody computers delete "$OLD_STAGING_ID" --yes

Omit name on recurring copies to receive an automatically generated name. A name the previous copy still holds is refused with 409. Keep the returned computer ID for checking the copy and replacing the previous generation.

The new staging copy has its own computer ID and URLs. An alias cannot be moved to another computer. To keep one proxy alias name for testers, delete it and create it again for the new copy once that copy is running; the address is down in between.

Copy production to staging

Path Parameters

Authentication

Not Authenticated

Use the authentication widget in the header to login or set an API token

Authentication: Authorization: Bearer header (auto-attached for trusted domains)

Custom Headers

Request Body (JSON)

Every developer gets an identical setup. One template produces any number of developer environments, each starting from the same filesystem, packages, and configuration. The source and destination projects must belong to your account. Create a project in your account for each developer, then copy the template into it.

Terminal window
# New team member Alice joins - copy template
hoody computers copy "$TEMPLATE_ID" --target-project "$ALICE_PROJECT" --name alice-dev-env
# Another developer Bob joins
hoody computers copy "$TEMPLATE_ID" --target-project "$BOB_PROJECT" --name bob-dev-env

Every developer starts from the same template. When the template changes, copy it again for anyone who needs the new version.

Copy template for new team member

Path Parameters

Authentication

Not Authenticated

Use the authentication widget in the header to login or set an API token

Authentication: Authorization: Bearer header (auto-attached for trusted domains)

Custom Headers

Request Body (JSON)

Copy staging only once it is running: a computer that is still copying cannot be copied.

Terminal window
set -eo pipefail
# Copy production to staging and wait for it
hoody computers copy "$PROD_ID" --target-project "$STAGING_PROJECT" --name staging-app --until-done -o json
# Set STAGING_ID to response.id from the JSON output
# Developers: Copy staging to personal envs
hoody computers copy "$STAGING_ID" --target-project "$DEV_PROJECT" --name alice-dev

To move changes down the chain, copy each level again from the one above it.

Terminal window
# Primary in US: PROD_US_ID
# Copy to EU
hoody computers copy "$PROD_US_ID" --target-project "$PROJECT_ID" --target-server-id "$EU_SERVER_ID" --until-done
# Copy to Asia
hoody computers copy "$PROD_US_ID" --target-project "$PROJECT_ID" --target-server-id "$ASIA_SERVER_ID" --until-done

After a US deployment, copy prod-us to each region again and delete the old regional copies.

A snapshot pins the copied filesystem. API-managed environment variables are inherited from the source computer’s current settings. Record and restore the intended environment-variable values separately when you need a reproducible deployment. Hoody has no atomic alias re-point, so the alias is deleted and recreated once the new computer is running. The recreated alias is enabled, never expires and takes the new computer’s realms; Switch traffic blue to green lists what to carry over from the old one.

Choose a new, unique snapshot name for every deployment and use that same name in the copy request. Use 2 to 64 letters, digits, _ or -, starting and ending with a letter or digit, such as release-20261113-01. Other characters are removed from the name, so release-2026.11.13 becomes release-20261113 and a copy that asks for the original spelling fails. Omit the copy’s name to receive an automatically generated one, so a repeated deployment does not collide with the previous copy’s name.

Terminal window
set -eo pipefail
# Set SNAPSHOT_NAME to a new, unique name for this deployment
: "${SNAPSHOT_NAME:?Set SNAPSHOT_NAME to a new snapshot name}"
# 1. Snapshot tested computer
hoody snapshots create -c "$TEST_ID" --alias "$SNAPSHOT_NAME"
# 2. Copy to production from that snapshot and wait for it
# (the sanitized alias supplied at creation is the snapshot's `name`)
hoody computers copy "$TEST_ID" --target-project "$PROD_PROJECT" --source-snapshot "$SNAPSHOT_NAME" --until-done -o json
# 3. Re-point alias to new computer (delete + recreate)
# Set NEW_PROD_ID to response.id from the JSON output and check it is running first
: "${NEW_PROD_ID:?Set NEW_PROD_ID to the new copy's id}"
hoody proxy aliases delete "$ALIAS_ID" --yes
# For program "http"/"https", --port is the port your app listens on inside the computer; substitute your own
hoody proxy aliases create --computer-id "$NEW_PROD_ID" --program http --port 3000 --alias prod --target-path /
Terminal window
# Copy production to test new feature
curl -X POST "https://api.hoody.com/api/v1/computers/$PROD_ID/copy" \
-H "Authorization: Bearer $HOODY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"target_project_id": "'"$SAME_PROJECT"'",
"name": "feature-auth-v2"
}'
# Set FEATURE_COPY_ID to the data.id returned by the copy.
# Check GET /api/v1/computers/$FEATURE_COPY_ID until data.status is running;
# if it is failed or stopped, resolve that before continuing.
# Then work on the feature in the copy (terminal, display and files are available).
# When the feature is complete, snapshot it
hoody snapshots create -c "$FEATURE_COPY_ID" --alias feature-auth-v2-complete
# Copy this feature computer to production
hoody computers copy "$FEATURE_COPY_ID" --target-project "$PRODUCTION_PROJECT" --until-done

Experiments run on a copy of your production data and do not change the source computer. The copy starts on its own and keeps the source’s environment variables. Before copying, make sure an application on the source cannot start on the copy against production services. Use test credentials and test endpoints in the copy, and check them before you enable the application.

Duplicate for parallel testing:

Terminal window
# Copy to test different approaches
hoody computers copy "$APP_ID" --target-project "$PROJECT_ID" --name variant-a --until-done
hoody computers copy "$APP_ID" --target-project "$PROJECT_ID" --name variant-b --until-done

Run the experiments in parallel without touching the original.

Instead of copying the current state, which might be broken, copy from a snapshot you know is stable:

Terminal window
# Instead of copying current state (might be broken):
# 1. Identify stable snapshot and read its exact "name" field
hoody snapshots list -c "$SOURCE_ID" -o json
# 2. Copy from that snapshot
hoody computers copy "$SOURCE_ID" --target-project "$PROJECT_ID" --source-snapshot "$SNAPSHOT_NAME" --until-done

A snapshot pins the copied filesystem. API-managed environment variables are inherited from the source computer’s current settings. Record and restore the intended environment-variable values separately when you need a reproducible environment.

Track which computers are copies, and how often you copy them again:

# computers-mapping.yml
production:
computer_id: 890abcdef12345678901cdef
server: node-us
copies:
- name: staging-api
computer_id: 01bcdef123456789abcdef01
project: staging-project
refreshed: after each production deployment
- name: prod-eu-replica
computer_id: 12cdef123456789abcdef012
project: production-project
server: node-eu
refreshed: monthly

To copy in the Hub, open Computers, open the source computer’s menu and choose “Make a copy…”. Enter a name, choose the destination server and project, then select “Make copy”. To copy through the API from this page, use the testers below. Omit target_server_id to use the same server as the source.

Copy a computer - omit target_server_id to use same server as source

Path Parameters

Authentication

Not Authenticated

Use the authentication widget in the header to login or set an API token

Authentication: Authorization: Bearer header (auto-attached for trusted domains)

Custom Headers

Request Body (JSON)

Basic copy, same server and same project:

Copy a computer

Path Parameters

Authentication

Not Authenticated

Use the authentication widget in the header to login or set an API token

Authentication: Authorization: Bearer header (auto-attached for trusted domains)

Custom Headers

Request Body (JSON)

Copy to a different project:

Copy to different project

Path Parameters

Authentication

Not Authenticated

Use the authentication widget in the header to login or set an API token

Authentication: Authorization: Bearer header (auto-attached for trusted domains)

Custom Headers

Request Body (JSON)

Copy to a different server:

Copy to different server

Path Parameters

Authentication

Not Authenticated

Use the authentication widget in the header to login or set an API token

Authentication: Authorization: Bearer header (auto-attached for trusted domains)

Custom Headers

Request Body (JSON)

SymptomCauseFix
Copy returns 404 or 403The source computer does not exist or is not accessibleGET /api/v1/computers/{source_id} should return 200
Copy returns 404The target project does not existVerify it with GET /api/v1/projects/{target_project_id}
Copy returns 400 SERVER_COMPUTER_LIMITThe target server is at its computer limitUse the capacity details in the error. For a current free server or paid subserver, a full-account signed-in session on the base API domain can also read its computer_capacity: for a free server through hoody servers list -o json or GET /api/v1/rentals, matching its server_id; for a paid subserver through GET /api/v1/rentals/{id} with the subserver’s id. Dedicated servers, API tokens, HTTP Basic and realm-scoped requests omit it. Choose another server or free a slot
Cross-server copy stays in copyingNetwork issues between servers can stall a copyContact support if persistent
The copy shows failedThe copy failedIt cannot be started: delete it and copy again
Copy takes very long (typical for 50 GB: ~3-5 minutes on the same server, ~10-15 minutes cross-server)Larger computers take longer: check data.disk.root.usage from GET /api/v1/computers/{source_id}/statsWait; 100+ GB computers can take 30+ minutes
Copy takes very longCross-server copies are slower: network transfer adds significant timeExpect longer times for cross-server copies
Copy takes very longHigh server load slows operationsTry during off-peak hours
Sync returns 409 ConflictSee sync errorsCopy the source again

The 404, 403 and 400 refusals in the first three rows create no copy.

TaskCall
Duplicate a computerPOST /api/v1/computers/{id}/copy
Sync a copy with its source (not available yet: 409 COMPUTER_SYNC_UNAVAILABLE)POST /api/v1/computers/{id}/sync
Check source_computer_id for copiesGET /api/v1/computers/{id}
Create a snapshot, the source for a pinned copyPOST /api/v1/computers/{id}/snapshots