This tutorial by Orca only deals with the specific task in the title. Orca’s SSH Worktree places Agent execution on the remote host, and each task must still be bound to an independent branch; the mobile version is suitable for following up and supplementing instructions, and should not bypass diff, testing, and merge approval.
All the following operations are first placed in the test repository, test account or service that listens only on the loopback interface. The domain name, username, path and key in the command are placeholders and need to be replaced before execution.
What are the components of the remote Orca workflow?
This section addresses “What are the components of a remote Orca workflow?” First record the current state, then perform the minimum action, and finally confirm the result with independent evidence.
For Orca, the basis for judgment is: Orca’s SSH Worktree places Agent execution on the remote host, and each task must still be bound to an independent branch; the mobile phone is suitable for follow-up and supplementary instructions, and should not bypass diff, testing, and merge approval. Don’t accidentally open more permissions at this stage.
|
|
Preserve command output and timestamp after execution. If the output depends on temporary variables in the current terminal, open a new terminal and check again.
SSH keys and host fingerprints are processed first
Process in the following order:
- Read the actual version and current configuration.
- Change only one setting relevant to this section.
- Run a read-only or revocable request.
- Check logs, exit codes, and final files.
- Revert the previous modification if it fails.
|
|
The completion criterion here is not that the interface appears, but that “SSH keys and host fingerprints are processed first” with repeatable results.
Create an independent Worktree for each Agent
| What to check | Acceptable performance | Signals that you need to stop |
|---|---|---|
| Create an independent Worktree for each Agent | Clear input and output scope | Automatically expand to other projects or accounts |
| Permissions | Get only the permissions you need to complete the task | Require administrator rights or full key |
| Log | Failed to locate and has been desensitized | Token, Cookie or private text appears |
| Rollback | Can restore the previous state | Modifications are irreversible and there is no backup |
|
|
Once the stop signal in the table appears, undo the changes in this section first and do not continue with subsequent automation.
How do remote directories correspond to local warehouses?
Prepare a success sample and a failure sample around “how the remote directory corresponds to the local warehouse”. Successful samples verify the normal path, and failed samples verify whether the restrictions really take effect.
|
|
It is recommended to record the following four items:
- Pre-execution version or Git commit.
- Actual input, no secret value recorded.
- Observable output, status code or diff.
- Recovery actions and review results after recovery.
If the cause of the failure is still unclear, modify only one variable at a time; do not change the port, runtime, provider, and proxy at the same time.
Save the baseline before starting the Codex task
This section solves the problem of “saving the baseline before starting the Codex task”. First record the current state, then perform the minimum action, and finally confirm the result with independent evidence.
For Orca, the basis for judgment is: Orca’s SSH Worktree places Agent execution on the remote host, and each task must still be bound to an independent branch; the mobile phone is suitable for follow-up and supplementary instructions, and should not bypass diff, testing, and merge approval. Don’t accidentally open more permissions at this stage.
|
|
Preserve command output and timestamp after execution. If the output depends on temporary variables in the current terminal, open a new terminal and check again.
Only forward the ports required by the task
Process in the following order:
- Read the actual version and current configuration.
- Change only one setting relevant to this section.
- Run a read-only or revocable request.
- Check logs, exit codes, and final files.
- Revert the previous modification if it fails.
|
|
The completion criterion here is not that the interface appears, but that “only forward the ports required for the task” has repeatable results.
Things you can and shouldn’t do on the mobile phone
| What to check | Acceptable performance | Signals that you need to stop |
|---|---|---|
| What you can and shouldn’t do on the mobile phone | Clear input and output scope | Automatically expand to other projects or accounts |
| Permissions | Get only the permissions you need to complete the task | Require administrator rights or full key |
| Log | Failed to locate and has been desensitized | Token, Cookie or private text appears |
| Rollback | Can restore the previous state | Modifications are irreversible and there is no backup |
|
|
Once the stop signal in the table appears, undo the changes in this section first and do not continue with subsequent automation.
How to handle when multiple Agents modify the same file
Prepare a success sample and a failure sample around “how to handle when multiple agents modify the same file”. Successful samples verify the normal path, and failed samples verify whether the restrictions really take effect.
|
|
It is recommended to record the following four items:
- Pre-execution version or Git commit.
- Actual input, no secret value recorded.
- Observable output, status code or diff.
- Recovery actions and review results after recovery.
If the cause of the failure is still unclear, modify only one variable at a time; do not change the port, runtime, provider, and proxy at the same time.
Compare candidate branches instead of mixing directly
This section addresses “comparing candidate branches rather than directly mixing”. First record the current state, then perform the minimum action, and finally confirm the result with independent evidence.
For Orca, the basis for judgment is: Orca’s SSH Worktree places Agent execution on the remote host, and each task must still be bound to an independent branch; the mobile phone is suitable for follow-up and supplementary instructions, and should not bypass diff, testing, and merge approval. Don’t accidentally open more permissions at this stage.
|
|
Preserve command output and timestamp after execution. If the output depends on temporary variables in the current terminal, open a new terminal and check again.
Run tests and reviews on remote hosts
Process in the following order:
- Read the actual version and current configuration.
- Change only one setting relevant to this section.
- Run a read-only or revocable request.
- Check logs, exit codes, and final files.
- Revert the previous modification if it fails.
|
|
The completion criterion here is not that the interface appears, but that “running the test and review on the remote host” has repeatable results.
Safely remove Worktree after merging
| What to check | Acceptable performance | Signals that you need to stop |
|---|---|---|
| Safely remove Worktree after merging | Clear input and output scope | Automatically expand to other projects or accounts |
| Permissions | Get only the permissions you need to complete the task | Require administrator rights or full key |
| Log | Failed to locate and has been desensitized | Token, Cookie or private text appears |
| Rollback | Can restore the previous state | Modifications are irreversible and there is no backup |
|
|
Once the stop signal in the table appears, undo the changes in this section first and do not continue with subsequent automation.
Disconnection, orphan processes and recovery
Prepare a success sample and a failure sample around “disconnection, orphan processes and recovery”. Successful samples verify the normal path, and failed samples verify whether the restrictions really take effect.
|
|
It is recommended to record the following four items:
- Pre-execution version or Git commit.
- Actual input, no secret value recorded.
- Observable output, status code or diff.
- Recovery actions and review results after recovery.
If the cause of the failure is still unclear, modify only one variable at a time; do not change the port, runtime, provider, and proxy at the same time.
Detect insufficient remote disk space in advance
This section solves the problem of “detecting insufficient remote disk space in advance”. First record the current state, then perform the minimum action, and finally confirm the result with independent evidence.
For Orca, the basis for judgment is: Orca’s SSH Worktree places Agent execution on the remote host, and each task must still be bound to an independent branch; the mobile phone is suitable for follow-up and supplementary instructions, and should not bypass diff, testing, and merge approval. Don’t accidentally open more permissions at this stage.
|
|
Preserve command output and timestamp after execution. If the output depends on temporary variables in the current terminal, open a new terminal and check again.
The forwarding port is only bound to the local loopback
Process in the following order:
- Read the actual version and current configuration.
- Change only one setting relevant to this section.
- Run a read-only or revocable request.
- Check logs, exit codes, and final files.
- Revert the previous modification if it fails.
|
|
The completion criterion here is not that the interface appears, but that “the forwarding port is only bound to the local loopback” has repeatable results.
Check candidate branch submission identity
| What to check | Acceptable performance | Signals that you need to stop |
|---|---|---|
| Check candidate branch submission identity | Clear input and output scope | Automatically expand to other projects or accounts |
| Permissions | Get only the permissions you need to complete the task | Require administrator rights or full key |
| Log | Failed to locate and has been desensitized | Token, Cookie or private text appears |
| Rollback | Can restore the previous state | Modifications are irreversible and there is no backup |
|
|
Once the stop signal in the table appears, undo the changes in this section first and do not continue with subsequent automation.
Save uncommitted changes before removing Worktree
Prepare a success sample and a failure sample around “Save uncommitted changes before removing the Worktree”. Successful samples verify the normal path, and failed samples verify whether the restrictions really take effect.
|
|
It is recommended to record the following four items:
- Pre-execution version or Git commit.
- Actual input, no secret value recorded.
- Observable output, status code or diff.
- Recovery actions and review results after recovery.
If the cause of the failure is still unclear, modify only one variable at a time; do not change the port, runtime, provider, and proxy at the same time.
Orca FAQ
Is it possible to skip the test environment and use Orca directly in the official project?
Not recommended. Complete at least one minimal success request, one intentional failure, and one recovery drill first.
The Orca command can be run but the result is incorrect, where should I check first?
First check the input range, actual effective configuration and upstream response, and then check the model summary. A normal process does not mean that the business results are correct.
How to prevent Orca keys or tokens from entering Git?
Use system environment variables, secret management, or configuration files outside the project, and search the diff before committing. Keys must be rotated after a breach is discovered.
What is the most common thing to miss when upgrading Orca?
It is most easy to miss configuration format, default listening address, permission scope and cache compatibility. Save the version and verification samples before upgrading.
Orca acceptance issues
Upon completion you should be able to answer the following questions:
- Which exact version are you using?
- Which directories, ports, accounts and external services can be accessed?
- How to return the successful result to the original data or Git diff?
- When the upstream fails, will it report an error, retry, or switch?
- Is it possible that the key appears in logs or history?
- How to return to the pre-modification state within ten minutes?
If any of these cannot be answered, Orca is still in trial status and should not expand permissions or tap into production automation.