Multi-Machine Workflow

This guide covers working with SkyBox across multiple machines, such as a laptop and desktop. Sessions prevent sync conflicts when you switch between machines.

How Sessions Prevent Sync Conflicts

When you run skybox up, SkyBox creates a session file that records which machine is actively working on the project. This file lives at:

<project>/.skybox/state.lock

Because this file is inside your project directory, Mutagen syncs it to your remote server and to any other machines syncing the same project. This means:

• When you start working on your laptop, your desktop sees the session file within seconds
• When you later sit down at your desktop, SkyBox warns you that the project is active elsewhere
• You can choose to continue anyway or go back to the original machine first

Sessions exist to protect you from sync conflicts, not to block you. If you know the other machine is idle (you just forgot to stop it), continuing is safe.

Common Scenarios

Forgot to Stop on Another Machine

You were working on your laptop, closed the lid, and now you are at your desktop:

skybox up my-project

This project is running on 'macbook-pro'.
? Continue anyway? (y/N)

If you choose yes:

• SkyBox creates a new session for your current machine
• The session file syncs to the laptop
• If you later return to the laptop and run a SkyBox command, it will see the session changed

This is safe as long as you are not actively editing on both machines simultaneously.

Intentional Switching Between Machines

When you finish work on one machine, stop the project cleanly:

# On your laptop when leaving
skybox down my-project

This removes the session file. Then on your other machine:

# On your desktop when arriving
skybox up my-project

No warning appears because no active session exists.

Working on the Same Machine

If you run skybox up on the same machine where the session is already active, SkyBox recognizes this and updates the session timestamp. No warning appears.

Checking Session Status

Use skybox status to see if a session is active and where:

skybox status my-project

The output includes a Session section:

Session
  Status:     active here
  Machine:    macbook-pro
  User:       alice
  Started:    2026-02-04T10:30:00Z

If no session is active, you will see:

Session
  Status:     none

Quick Status Check

To see all projects at once:

skybox status

The table shows session status for each project.

Recovering from a Crashed Machine

If your laptop died, lost power, or you simply forgot to run skybox down:

1. Wait for session expiry — sessions automatically expire after 24 hours. After that, skybox up on another machine proceeds without any warning.
2. Continue past the warning — if the session hasn't expired yet, skybox up will warn you that the project is active on the other machine. Choose "Continue anyway" since you know the machine is offline.
3. Force shell access — if you just need a shell without updating the session:

   skybox shell my-project --force

Your project files are safe on the remote server regardless. No data is lost when a machine crashes.

Session Expiry

Sessions expire after 24 hours. This handles cases where a machine crashed or lost network connectivity before running skybox down. Expired sessions are treated as inactive.

What Sessions Are NOT

Sessions are a personal safety feature for one person working across multiple computers. They are not a team collaboration tool.

For team collaboration, use Git.

• Multiple team members should each have their own remote folder or remote server
• Use branches and pull requests to coordinate code changes
• SkyBox remotes are for offloading disk space, not sharing workspaces

If two people try to work on the same SkyBox project simultaneously, you will have sync conflicts regardless of sessions. Sessions only help when one person forgets to stop on another machine.

Session File Details

The session file contains:

{
  "ownership": {
    "owner": "alice",
    "created": "2026-02-04T09:00:00Z",
    "machine": "macbook-pro"
  },
  "session": {
    "machine": "macbook-pro",
    "user": "alice",
    "timestamp": "2026-02-04T10:00:00Z",
    "pid": 12345,
    "expires": "2026-02-05T10:00:00Z",
    "hash": "7b9e4c5af2c48b3c1e7d9a0c4d0f3e6a9b8c2d1f4e7a6b5c3d2e1f0a9b8c7d6"
  }
}

• machine: Hostname of the machine that started the session
• user: Username who started it
• timestamp: When the session started
• pid: Process ID (used to detect stale sessions on the same machine)
• expires: When the session automatically expires (24 hours from start)

Related Commands

Command	Usage in this workflow
skybox up	Start a project on the current machine
skybox down	Stop a project before switching machines
skybox clone	Clone a project on a new machine
skybox status	Check session status across machines
skybox shell	Access container shell (supports --force)

Next Steps

• Daily Development - Day-to-day workflow patterns
• New Project Setup - Creating and cloning projects