# Choose a Session folder and control which settings are saved

Choose a focused Start Folder, preserve your setup draft when canceling or confirming the Folder Picker, and decide whether Session settings apply once or persist with the project.

Use Session Setup to choose a focused task root, keep the rest of your draft intact while you browse, and decide whether eligible settings apply only to this launch or are saved with the project.

Safe outcome:

before you select

Start Session

, the visible

Start Folder

is the focused task folder you intended, the provider settings are still correct, and the config option matches whether you want future Sessions to reuse those settings. After launch,

Working Directory

and

Workspace Policy Root

both identify that same folder.

## 1. Prepare a focused task folder

Start on the Oysterun **Sessions** page. You need access to the intended Host and an existing folder that the Host can read.

1. Put only the files needed for this task in one focused folder.
1. Avoid selecting a disk root, your whole home folder, or a broad shared parent merely to make setup easier.
1. Confirm that the provider you intend to use is already available on this Host.

Current folder-protection limit:

Allowed Paths

is intentionally unavailable and hidden in the normal product. A narrow Start Folder makes your intended working scope visible, but it is not a provider-independent security boundary. Continue to review provider permission requests and stop if they name an unexpected path.

## 2. Know which visible settings win

A fresh Session Setup combines settings in this order:

1. **Host defaults** seed a new form, including the default Browse Root and runtime.
1. **Project settings** from the selected folder can supply shared Session defaults.
1. **Your current Session Setup choices** are the launch-time values. Treat the values visible in the form as the draft you are about to use.

Shared project settings belong in `.oysterun/config.json`. Passwords, tokens, and other private values do not belong there. A later runtime-only change in **Session Profile** affects the running Session unless you explicitly choose its update-config option.

## 3. Open Session Setup and review the draft

1. On **Sessions**, choose **New Session**.
1. Confirm that the page title is **Session Setup**.
1. Review **Agent ID**, **Session Name**, **Agent Runtime**, **Model**, reasoning, and **Start Folder**.
1. Change the provider fields now if this Session needs values different from the displayed defaults.

**Checkpoint:** before opening the picker, you can state the exact Start Folder, Agent ID, Session Name, provider, model, and reasoning value shown in the draft.

![Session Setup showing its Agent ID, Session Name, complete task Start Folder, Choose folder control, and Codex selected as Agent Runtime.](../assets/publication/session-setup-confirmed.png)

Visible checkpoint: the settled Session Setup shows the identity fields, complete task folder, folder control, and selected Codex runtime together.

## 4. Confirm or cancel a folder choice without losing the draft

Browsing does not commit a folder. Use **Go back** to cancel and return to the same draft, or use the triangular **Use this folder** action beside the breadcrumb to confirm the folder currently shown.

![Folder Picker focused on a task folder with the complete breadcrumb, Go back control, and triangular Use this folder action visible.](../assets/publication/folder-picker-focused.png)

Visible checkpoint: the complete breadcrumb names the focused task folder; Go back cancels, while the triangular Use this folder action confirms the folder shown.

### Cancel the picker

1. Use the **Choose folder** control beside **Start Folder**.
1. On **Folder Picker**, browse to another folder if you want to inspect it.
1. To cancel, use the top-bar **Go back** control without choosing **Use this folder**.

**Cancel checkpoint:** Session Setup returns with Start Folder, Agent ID, Session Name, provider, model, and reasoning unchanged. Folder Picker navigation alone does not commit a choice.

### Confirm the intended folder

1. Open **Choose folder** again and navigate to the focused task folder.
1. Choose **Use this folder** for that exact folder.
1. Back on Session Setup, read the complete **Start Folder** value rather than relying on the last folder name alone.
1. Recheck Agent ID and Session Name if Oysterun generated them from the folder, then recheck the provider, model, and reasoning values you entered.

**Confirm checkpoint:** Start Folder now shows the intended folder. **Use this folder** updates the Session Setup draft; it does not start a Session or write project settings by itself.

## 5. Decide whether the settings are saved

Session Setup has one launch action, **Start Session**. Before using it, read the config checkbox label because its meaning depends on whether the selected folder already has a shared config file. The checkbox label describes what checking it will do.

### The folder already has `.oysterun/config.json`

- Check **Update .oysterun/config.json** to save eligible shared values for later Sessions.
- Leave it unchecked to use the visible choices for this launch without changing the existing shared config file.

### The folder has no shared config file

- The label becomes **Do not create .oysterun/config.json**.
- Leave it unchecked for the normal behavior: create the shared config when the Session starts.
- Check it when you want this launch to leave the shared config absent.

If you want to cancel the entire setup, leave Session Setup without choosing **Start Session**. A folder choice in the draft is not a durable save.

## 6. Start once and verify the selected root

1. Review the complete Start Folder and config option one final time.
1. Choose **Start Session**.
1. On desktop or phone, when the Session chat opens, use the top-bar **More Options** control (vertical ellipsis), then choose **Session Profile**.
1. Confirm that **Working Directory** is the complete Start Folder you selected.
1. In **Workspace Policy**, confirm that **Root** shows the same complete folder.

![Session Profile showing the complete Working Directory and an identical Workspace Policy Root for the same Session.](../assets/publication/session-profile-root.png)

Visible checkpoint: the same Session reports one complete task path as both its Working Directory and Workspace Policy Root.

Final checkpoint:

the running Session reports the intended folder as both Working Directory and Workspace Policy Root, and you know whether its eligible shared settings were launch-only, updated, newly created, or deliberately left absent.

## Recover safely and know when to stop

- **The picker cannot open the folder:** return to Sessions, confirm the Host can read the folder, and choose another focused folder you own.
- **Cancel changed the draft:** do not launch. Return to Sessions, open a fresh New Session, and repeat the cancel check; the current product is expected to preserve the draft.
- **The config option is not the mode you intended:** correct it before Start Session. Do not hand-edit runtime files as the primary recovery.
- **Session Profile shows a different Root:** do not perform file operations. Stop using that Session and create a new one with the intended Start Folder.
- **An Allowed Paths control appears:** do not rely on it as active folder protection. It is a diagnostic-only surface in the current product.

**Safe stop:** do not choose Start Session until the full path, visible provider settings, and config option are all correct.