Setting Up Remote Agent Environment

Set up a remote machine for development or a coding agent. You will need SSH access, Git access to the repository, and the runtime versions specified by the project.

The examples use dev-box as the SSH alias and alice as the DreamLake account. Replace both with your own values.

Connect to the machine

Run on your local machine:

ssh dev-box

For provisioning and network/key prerequisites, see Resource setup.

Prepare a checkout

Run on the remote machine. This example creates a separate DreamLake CLI checkout and checks out a specific commit. Replace the revision before running it.

bash <<'SH'
set -eu
TASK_REVISION='REPLACE_WITH_FULL_COMMIT_SHA'
case "$TASK_REVISION" in
  REPLACE_*) printf '%s\n' 'Set TASK_REVISION first'; exit 1 ;;
esac

mkdir -p "$HOME/workspaces"
TASK_DIR=$(mktemp -d "$HOME/workspaces/dreamlake-cli-task.XXXXXX")
git clone https://github.com/dreamlake-ai/dreamlake-cli.git "$TASK_DIR"
cd "$TASK_DIR"
git switch --detach "$TASK_REVISION"
git switch -c work/remote-dev
printf 'Checkout: %s\n' "$TASK_DIR"
git rev-parse HEAD
SH

Use the printed checkout path as the working directory for your editor or agent. Each concurrent task should have its own checkout and branch.

Install the Node and pnpm versions specified by the checkout, then run from that directory:

bash <<'SH'
set -eu
node --version
pnpm --version
pnpm install --frozen-lockfile
pnpm run build
pnpm test
SH

Configure access

Set up the services your project uses on the remote machine.

Desktop keychain credentials and hardware-backed keys require remote login or a separate remote credential. For existing deployments, retain the encryption keys needed to read stored data and use the authoritative Terraform state/backend.

Upload configuration files to the vault

Use a CLI version with vault support and a vault-enabled server. See #241 for release and deployment status.

Run on the local machine:

dreamlake login
dreamlake vault add --help

# Application configuration.
dreamlake vault add -n alice/remote-agent/app-env \
  --stdin --file-name .env < ./service/.env

# A selected SSH private key.
dreamlake vault add -n alice/remote-agent/ssh-key \
  --stdin --file-name id_ed25519 < "$HOME/.ssh/remote_agent_ed25519"

# A selected cluster configuration.
dreamlake vault add -n alice/remote-agent/kubeconfig \
  --stdin --file-name config < ./selected-cluster.kubeconfig

dreamlake vault list -p alice/remote-agent
dreamlake vault show -n alice/remote-agent/app-env

Run only the uploads you need. --stdin preserves UTF-8 text and trailing newlines; the JSON-encoded value is limited to 64 KiB. --file-name records a suggested filename. To replace an existing entry, inspect its revision with show and pass that revision with --if-match.

dreamlake upload is for episode assets. Use dreamlake vault add for secrets.

Select SSH entries to import

Selected SSH import is available in the released clients. See the credential guide for supported versions, CLI/Python usage and current limitations.

Run in an authenticated interactive terminal on your local machine:

dreamlake vault import --ssh -p alice/remote-agent

The checklist starts with no entries selected. Profiles and private keys are separate items:

Select SSH entries to upload

[ ] dev-box profile       dev@dev.example.com
[ ] dev-box private key   ~/.ssh/dev_box
[ ] bastion profile       dev@jump.example.com
[ ] bastion private key   ~/.ssh/bastion

Space: select    Enter: review selected    Esc: cancel

Select the entries you want, review their vault destinations, and upload the selection. Only checked entries are uploaded. An empty selection or cancellation before upload writes nothing. Private keys and jump-host entries require their own selection.

To inspect discovered items without reading private keys or contacting the vault:

dreamlake vault import --ssh -p alice/remote-agent --dry-run --json

See SSH import for the selection and retry behavior.

Restore a file remotely

Log in on the remote machine:

dreamlake login

From your application checkout, restore the saved environment file to service/.env. The service directory must already exist. This example creates a mode-0600 file and fails if the destination exists or retrieval fails.

python3 - <<'PYTHON'
import json
import os
from pathlib import Path
import subprocess

destination = Path("service/.env")
if not destination.parent.is_dir():
    raise SystemExit("Create the service checkout first")
result = subprocess.run(
    ["dreamlake", "vault", "get", "-n", "alice/remote-agent/app-env", "--to-json"],
    stdout=subprocess.PIPE, stderr=subprocess.PIPE,
)
if result.returncode:
    raise SystemExit("Vault retrieval failed")
value = json.loads(result.stdout)
if not isinstance(value, str):
    raise SystemExit("Expected a text-file entry")
fd = os.open(destination, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, "wb") as output:
    output.write(value.encode("utf-8"))
print("Created service/.env")
PYTHON

Change the entry name and destination for other files. Use mode 0700 for SSH and credential directories. For individual environment variables, see Environment exports.

Run development tools or an agent

Start your editor or coding agent in the remote checkout under the account that owns the configuration files. Use the project's commands to start the service and run its checks. Applications that read .env files must use the configured file location; other programs need the variables exported into their process environment.

The DreamLake CLI development example uses pnpm run build and pnpm test. Application integration tests may additionally need the configuration restored above. Set up remote agent authentication separately if your agent requires it.

Check the setup

• Confirm the checkout revision with git rev-parse HEAD.
• Run the project's build and tests from the remote account.
• Check required configuration files exist and have the intended permissions.
• Verify access to each required API, registry or cluster with a read-only call.
• Verify SSH access with a fresh connection.

Keep secret values out of terminal output and logs. If a check fails, fix its reported dependency, configuration or authentication error and rerun that check.