How To Use VS Code Remote Agent Sessions? 2026 Remote Mac Deployment

Remote Agent Sessions is a preview capability. The first question is not whether the Agents window can display a host. The first question is whether the host is safe to use for a limited engineering test.

Separate these three states:

• SSH connection works: your client can authenticate and open a session.
• Workspace access works: the Agent can select the intended directory and read the repository.
• Development toolchain works: the same remote account can invoke the required shell tools, Xcode commands, dependencies, and tests.

These states are independent. A Mac may accept SSH while the Agent cannot access the repository. A workspace may open while the login shell misses Homebrew or Node paths. A successful command-line Xcode check may still say nothing about Simulator availability or signing assets.

Before you continue, record:

• A disposable macOS account or an explicitly isolated personal account.
• A host label such as <REMOTE_MAC_HOST>.
• A repository path such as <WORKSPACE_PATH>.
• A branch or commit that can be safely modified.
• A rollback command or snapshot procedure.
• A maintainer who can disable access without relying on the Agent session.

Use the Apple Remote Login guide to verify that SSH access is enabled on the Mac. Do not confuse a reachable port with a complete development environment.

Stop condition: If you cannot identify the remote account, workspace path, owner of the credentials, and rollback method, do not connect an Agent to the node.

SSH and Dev Tunnel solve different operational problems. Neither is automatically better.

SSH fits a host-controlled network

Use SSH when you already manage:

• macOS user accounts and public keys;
• firewall and network access;
• host naming and access logs;
• shell configuration;
• rotation and revocation of credentials.

The VS Code Remote SSH documentation is the relevant reference for client setup and host configuration. SSH is usually easier to reason about when the Mac sits inside a controlled network and your team already has a standard key-management process.

Its weak points are operational. You must expose or route SSH correctly, maintain client compatibility, revoke keys, and understand which account starts the remote process. A developer who can open an interactive terminal may still use a different shell environment from the Agent host.

Dev Tunnel fits managed reachability

A Dev Tunnel can avoid directly exposing SSH to every operator network. It can be useful when the remote Mac is behind a network boundary and the connection must be associated with an account-managed identity.

The VS Code Dev Tunnels documentation is the authority for the tunnel flow. Authentication is not optional for an acceptable shared development setup. Anonymous access must not be used for a node that can read private repositories or reach signing material.

Its weak points are different:

• the tunnel service becomes part of the recovery path;
• account identity and tunnel ownership need operational documentation;
• a stopped tunnel can look like a dead Mac;
• browser or client access may hide which local credential initiated the session.

Use this decision tool:

• Select SSH if your team owns the network route, host accounts, and key lifecycle.
• Select authenticated Dev Tunnel if you need account-based access through a managed tunnel and can monitor tunnel state.
• Select neither if you cannot audit who connected, which account ran the Agent, or how access is revoked.

The Agents window must identify the intended host, let you choose the intended remote directory, and start a session under the expected identity. Save screenshots or logs of these states during the trial. Do not record secrets in those notes.

The first functional check is deliberately small. Do not begin with a release build.

In the VS Code Agents window:

1. Select the configured remote connection.
2. Confirm that the displayed host matches <REMOTE_MAC_HOST>.
3. Select <WORKSPACE_PATH>, not a broad home directory.
4. Start a new Agent session.
5. Ask for a read-only listing of the current directory.
6. Confirm the repository root and current branch.
7. Request a harmless file read.
8. End the session and reconnect.

The goal is to prove that the remote Agent can identify the same machine, directory, account, and repository on two separate connections.

Remote Agent Sessions should not be confused with four nearby technologies:

• Remote SSH: a remote development transport and workspace mechanism.
• Dev Tunnel: a managed connection route that can support remote access.
• VS Code Server: the remote-side service used by some VS Code remote workflows.
• Traditional CI Runner: an automated job executor with a pipeline-defined lifecycle.

An Agent session is an interactive or delegated command workflow. It is not automatically a durable CI runner. It does not automatically preserve a build after a client disconnects. It does not automatically obtain signing permission.

The Agent must be tested as an execution identity, not only as a chat interface. The important evidence is whether the remote process can read, modify, inspect, and test the intended project with the expected environment.

Run these checks through the Agent:

whoami
pwd
echo "$SHELL"
git rev-parse --show-toplevel
git status --short
command -v git
command -v xcodebuild

Use placeholders for real values. Do not paste private tokens, certificate content, or production URLs into prompts.

Then run a controlled loop:

1. Ask the Agent to read one known source file.
2. Ask it to propose a small change without applying it.
3. Review the proposed diff.
4. Permit the change only inside <WORKSPACE_PATH>.
5. Run a repository-specific dependency check.
6. Run the smallest non-destructive test.
7. Inspect git diff and the command output.
8. Revert the change if the trial is only an environment test.

A local terminal may succeed while the Agent fails. Investigate these boundaries in order:

• PATH differs between an interactive shell and a login shell.
• The Agent starts under another macOS account.
• The selected directory is readable but not writable.
• Repository credentials are available locally but not to the remote process.
• An approval request is waiting in the client.
• A tool is installed through a shell startup file that the Agent does not load.

The VS Code Agent approvals guidance matters here. Approval state is part of the execution path. A command that has not been approved is not evidence that the environment is broken.

The phrase “Xcode works” is too broad for a remote Mac. Verify the toolchain in layers.

Level one: command-line tool availability

Start with:

xcode-select -p
xcodebuild -version
xcodebuild -showsdks

The Apple Xcode command-line tool reference explains the command-line surface. The active developer directory and installed SDK list must match the project’s requirements.

Level two: project resolution

From the actual workspace, inspect the project or workspace:

xcodebuild -list -workspace <WORKSPACE>.xcworkspace

If the project uses a project file instead:

xcodebuild -list -project <PROJECT>.xcodeproj

Confirm that dependencies are present and that the selected scheme exists. A command that runs in the home directory proves very little.

Level three: non-graphical build or test

Use a controlled destination and a non-release configuration:

xcodebuild \
  -workspace <WORKSPACE>.xcworkspace \
  -scheme <SCHEME> \
  -destination '<DESTINATION>' \
  -configuration Debug \
  build

The exact build settings depend on the project. Apple’s build settings reference should be used when a setting, SDK, signing option, or destination behaves unexpectedly.

Level four: Simulator, signing, and release

Do not collapse these into the previous result.

• xcodebuild can be executable while Simulator runtimes are missing.
• A Simulator can be available while the project lacks signing access.
• A signed local build can work while distribution credentials are absent.
• A release archive can complete while unattended publishing is unsafe.

Remote Agent Sessions do not create a universal promise for Simulator control, signing, or production release. Test each capability on the real Mac and under the same account that will run the Agent. Move graphical sessions, certificate access, Team ID values, distribution profiles, and publishing tokens into a separate acceptance process.

A shared Mac needs stronger boundaries than a personal development node. The remote entry point and the Agent approval model multiply each other’s risk.

For a personal trial:

• use a dedicated repository checkout;
• keep the working directory narrow;
• avoid storing long-lived tokens in shell profiles;
• require approval for writes outside the repository;
• disable the test account after the trial if it is no longer needed.

For a shared node:

• use separate macOS accounts where possible;
• avoid a shared home directory for unrelated projects;
• use separate Git worktrees or checkouts;
• restrict certificate and provisioning-profile paths;
• separate development credentials from release credentials;
• document who can approve commands;
• log permission changes and access removal.

The VS Code Agent security guidance should be read before changing approval behavior. Automatic approval may reduce prompts, but it also increases the consequence of a malicious instruction, an unsafe repository script, or a mistaken path. Never combine automatic approval with broad access to signing certificates and production tokens during the first trial.

Every permission increase needs three records:

• what changed;
• why the change was necessary;
• how to disable or reverse it.

Experience rule: A successful build is not a security acceptance result. Treat source access, command approval, signing access, and publishing access as separate permissions.

A remote Mac is not ready for long-running Agent work until you know what happens when the client disappears.

Run the recovery test in an isolated repository:

1. Start an Agent session and record the host, account, workspace, and branch.
2. Begin a harmless command that produces visible output.
3. Disconnect the local VS Code client.
4. Check whether the remote process stops, continues, or becomes unknown.
5. Restore the connection and inspect the workspace state.
6. Stop the Dev Tunnel if that is your selected route.
7. Re-enable the tunnel and repeat the connection check.
8. Restart the Mac.
9. Confirm that macOS reaches the login state and the selected remote access method returns.
10. Reconnect the Agent and repeat whoami, pwd, repository status, and a harmless command.

Record observable outcomes, not assumptions:

• Did the session disappear from the Agents window?
• Did a command continue after the client disconnected?
• Was the workspace locked or modified?
• Did the tunnel return without manual intervention?
• Did Remote Login remain enabled?
• Did the Agent host start under the same account?
• Did approval state remain expected?
• Did the repository require cleanup?

A reconnecting session is not the same as a resumed job. If a build, migration, or file modification can be left half-complete, use an external job marker, idempotent scripts, and a manual recovery command. Do not ask the Agent to infer whether an interrupted operation finished.

After the trial, choose one of three outcomes.

Continue a limited trial

Choose this when:

• the host identity is clear;
• SSH or authenticated Dev Tunnel access is repeatable;
• the Agent reads and modifies only the intended workspace;
• the Xcode command-line checks pass;
• approval prompts are understood;
• restart behavior is documented;
• no production credentials are required.

Keep the node isolated and use test repositories until repeated runs show stable behavior.

Restrict the Agent to controlled execution

Choose this when the coding loop works but one boundary remains unresolved. Examples include missing Simulator validation, uncertain tunnel recovery, inconsistent shell paths, or unavailable signing assets.

In this mode, permit source inspection, small changes, and non-release checks. Keep release certificates, publishing tokens, and production repositories outside the Agent’s reach.

Delay production access

Choose this when:

• the Mac cannot reliably return after restart;
• the remote account is unclear;
• the workspace path is too broad;
• approval behavior cannot be audited;
• credentials are shared;
• the only evidence is a successful SSH login;
• a build result cannot be reproduced under the Agent account.

Do not turn a preview feature into an unattended production control plane without evidence from the exact Mac, project, account, and recovery path.

Can VS Code Remote Agent Sessions connect to a macOS host?

Yes. The current preview supports remote Agent sessions through SSH, an authenticated Dev Tunnel, or a browser-managed entry point, provided the Mac is powered on and reachable over the network. A successful connection only proves that the session can reach the host. You still need separate checks for the workspace, shell, tools, permissions, and repository access.

Can a remote Agent session run xcodebuild directly?

It can run xcodebuild when the selected remote account can access the intended project and the Mac exposes a valid Xcode command-line toolchain. Test xcode-select, the active developer directory, project dependencies, and a non-release build first. Simulator access, signing, distribution, and unattended publishing require separate acceptance because they are not universal promises of Remote Agent Sessions.

Should you choose SSH or Dev Tunnel for a remote Mac?

Choose SSH when you control the network entry point, user accounts, keys, and host lifecycle. Choose an authenticated Dev Tunnel when you need a managed connection path without directly exposing SSH to your operator network. Do not use anonymous tunnel access for an engineering node. The decision depends on identity ownership, audit requirements, client dependencies, and recovery procedures.

What happens to an Agent session after the remote Mac restarts?

Assume the session is interrupted, not preserved. After a restart, verify that macOS is online, Remote Login or the authenticated tunnel is available, the Agent host can start again, and the workspace remains accessible. Re-run a harmless command before allowing changes. A reconnecting client does not prove that an interrupted build, approval state, or background process resumed safely.

How do you isolate repositories and credentials on a shared Mac?

Use separate macOS accounts or tightly scoped workspaces, restrict repository paths, and keep signing certificates, distribution profiles, cloud tokens, and deployment keys outside the Agent's normal working area. Record every approval change and define a stop condition. Automatic approval combined with a remote entry point should be treated as elevated risk, not as a convenience setting.

A Windows or Linux workstation plus ad hoc access to a personal Mac can work for occasional checks, but it has three recurring weaknesses: the Mac may be offline, the environment may drift between users, and recovery depends on whoever owns the hardware. A local Mac mini adds another burden: upfront hardware cost, physical maintenance, and limited access when the device is behind a home network or already serving another workload.

If you need a disposable, real macOS node for this validation, CALMVPS Mac rental options can provide a separate environment without making your primary workstation the test boundary. Review the available remote Mac access options only after defining the account, repository, credential, and recovery checks above.

The sensible sequence is to rent a short-lived Mac environment, run the minimum Agent and Xcode acceptance tests, then decide whether the workload justifies a longer commitment. For teams that need a persistent node, CALMVPS may be a cleaner operational fit than an unmanaged personal Mac, but it is still your responsibility to isolate repositories, control approvals, and keep release credentials out of the trial.