See the complete route index at https://docs.crusible.dev/llms.txt before following links.

# Your first worktree channel

Create a channel with a machine, run a command and attach a file.

<!-- https://docs.crusible.dev/start/first-worktree/ · doctype: tutorial · role: member · reviewed: pending human review -->


This tutorial starts a channel with a machine and runs a harmless command.
The channel form chooses the branch behaviour; it doesn't offer a branch picker.


1. <p>Open the channel creation dialog from the channel list.</p>
 (Result: The channel creation dialog shows its name, topic and a preview.)

1. <p>Enter a name and read the topic and preview.</p>
 (Result: The preview identifies the channel the dialog will create.)

1. <p>Enable <strong>Start a Sandbox</strong> if it&rsquo;s offered. Choose a size from the displayed
options. Choose an image when a list is available; an empty list uses the image supplied by the application.</p>
 (Result: The dialog shows the available size and image choices.)

1. <p>Submit the dialog once. Wait for the machine card to offer <strong>Open terminal</strong>.</p>
 (Result: The new channel opens and its machine card reports preparation progress.)

1. <p>Select <strong>Open terminal</strong>. Check the selected machine before entering a command.</p>
 (Result: The terminal opens on the channel's machine.)

1. <p>Run <code>pwd</code>.</p>
 (Result: The shell prints its current directory.)

1. <p>Select <strong>Attach files</strong> and choose a small file without credentials or private keys.
Wait for the transfer result before using the file in a command.</p>
 (Result: The upload queue reports the transfer result.)

1. <p>Leave the channel and return. Check the machine card before reopening the terminal.
Use <strong>Wake</strong> if that is the action offered.</p>
 (Result: The machine state determines whether you can attach or need to wake it.)

- **If this doesn't work:** <p>If <strong>Start a Sandbox</strong> is unavailable, stop before creating a channel expecting a shell.
If preparation fails, read the machine card&rsquo;s reason. Use <strong>Retry</strong> only when offered.
A missing repository or a permission refusal needs that condition corrected first.
An upload failure remains in the queue; check the message before selecting the file again.</p>





You have run a command on the channel's machine and checked its file-transfer result.
This tutorial doesn't require a commit or promise that an agent starts automatically.

- [Terminal](https://docs.crusible.dev/reference/surfaces/terminal/) — Shells, machine selection, terminal tabs, file uploads and connection controls.- [A machine shows “Lost the link”](https://docs.crusible.dev/troubleshooting/a-machine-shows-lost-the-link/) — Crusible dropped the connection to a machine and is retrying. What is safe, what to read while you wait, and when to bring in an admin.