Files, ports and pages

Last updated: 2026-10-30

Your shells are not the only thing on your hosts that you need. SpectaShell moves files between a host and your device, opens the ports of a host's programs on your device, and shows the pages they serve beside the shell that started them — all over the SSH connection you already use. Nothing needs to be installed on the host for this, and SpectaShell opens no port of its own.

Files in a shell#

Sending a file to a host#

Drop files on a pane on a host. They are uploaded into your Downloads folder there (the one the host's desktop calls Downloads, else ~/Downloads), and once all of them have arrived their paths are typed at the cursor, ready for a command. A name already taken there gets a number: report 2.csv.
Send File to Host…, in the ⋯ menu at the right of the tab strip, picks files to send the same way. On the iPad and iPhone, Send Photo to Host… picks from Photos; a photo goes as a JPEG, which programs on a host can read.
Each file shows a line under the pane while it goes, with its progress and Cancel. One that failed says why until you choose Dismiss.
A file dropped on a shell on your Mac is not copied: its path is typed, as Terminal does.

Opening a file a shell printed#

A path a program prints in a shell on a host — src/app.py:42, a name in ls — opens from the host when you open it as a link (see Working in the terminal). A text file opens in the text viewer described in Viewing and editing text; anything else is downloaded and shown in Quick Look, where you can open it in its app, share it or save it.

Opening the shell's folder#

Open Folder in SFTP, in the ⋯ menu at the right of the tab strip, shows the folder the shell on a host is in, in the file manager below.

The file manager#

SFTP, in the sidebar on the Mac and the iPad and in the tab bar on the iPhone, is a file manager for your hosts and for this device. It reads and writes a host's files over SFTP, through the same login as its shells; the copying, moving and compressing are done on the host itself, so a large copy there never passes through your device.

It opens on Choose a place: this device first — This Mac, This iPad or This iPhone — then the hosts of your book. Choose one to open its home folder.

This Mac is your whole Mac, from your home folder.
This iPad and This iPhone are SpectaShell's own folder, which the Files app shows as On My iPad › SpectaShell, and the folders you add from Files (see Places and favourites).

A host needs SFTP for the file manager; most do. A host without it — some routers — says so, and its shells can still receive dropped files.

Moving around#

The path bar at the top has Back, Forward and Enclosing Folder, then the place's name and the folders down to the one you are in. Click a folder in the path to go there; the place's name opens its places as a menu.
Open a folder with a double-click on the Mac, or a tap on the iPad and iPhone. With a keyboard, Return opens the selection (Command-Down Arrow too, on the Mac), Space shows it in Quick Look, Command-Delete moves it to the Trash, and typing a name selects the item it starts.
The folder shown is asked again every 2 seconds, and what changed appears by itself: a program's new outputs, a file another device added.
The folder's menu, the circled ⋯ beside the search field, has New Folder…, Paste, Undo and Redo, the view as List or as Icons, Show Hidden Files, Sort By, Reload, and Choose Another Place.
The table shows Name, Permissions, Size and Modified; click a column's title to sort by it. The icons show pictures as small pictures, made on the host when it has a tool for it. Folders come before files.

The status line at the bottom says how many items are shown, what the last change did with its Undo, or the change running with Stop.

Searching#

Type in the search field to find items by name. While there is text in it, choose:

This Folder: only the folder shown, as a filter.
Subfolders: every folder below it, with what is found streaming in. The status line counts what was found and the folders searched; the search stops at 5,000 items.

Upper and lower case do not matter. Hidden items are searched only while they are shown.

What you can do with items#

Right-click an item (touch and hold on the iPad and iPhone) for its menu. Select several to act on them all.

Open, for a folder; Quick Look, for a file: text opens in the text viewer, anything else in Quick Look.
Get Info: the item's kind, size (a folder's counted as you watch), where it is, when it was modified and changed, its owner and group, and its permissions, which you can change with Apply.
On the Mac, Download to Downloads: the files go into your Mac's Downloads folder and are shown in the Finder. On the iPad and iPhone, Share…: Save Image, Save to Files and the rest.
Rename…, Duplicate, which makes a copy named "name 2", Compress into a zip, and Extract for an archive (zip, and tar with any compression). A host compresses and extracts with the tools it has — zip, unzip, tar, bsdtar or python3 — and says which one it lacks if it has none. What an archive holds never lands outside its folder.
Move To… and Copy To… choose a folder of the same place, then Move Here or Copy Here.
Copy, Cut and Paste: Paste puts copied items here, or moves cut ones, once. Files copied in the Finder or Files are uploaded; a path copied in a terminal is found on the host.
Copy Path copies each item's full path.
Add to Favourites, for a folder.
Move to Trash.

The Mac's Edit menu works in the file manager: Undo (Command-Z), Redo (Shift-Command-Z), Cut (Command-X), Copy (Command-C), Paste (Command-V) and Select All (Command-A).

Upload, at the right of the path bar, picks files to put in the folder shown — From Files…, and on the iPad and iPhone From Photos…. You can also drop files on the folder from the Finder or the Files app, or onto a folder in it.

Drag items out to the Finder, Files or Photos: each file is downloaded as it is dropped, so Photos gets the picture itself.

Dragging within a place#

Drag items onto a folder, a folder of the path bar or a place in the sidebar to put them there. As in the Finder, they are moved within one disk and copied from another, the originals kept. On the Mac, hold Option to copy.

When a name is taken#

When an item goes where one of the same name already is — a copy, a move, a drop, a paste, Put Back — you are asked, with both items' size and date:

Replace: the one there goes to the Trash first, so this can be undone.
Keep Both: the new one gets a number.
Skip leaves this one, and Stop stops the rest.
Apply to All answers the same for the items left.

A rename never replaces anything.

Undo#

Every change can be undone: a move goes back, a trashed item is put back, a copy, a new folder or an archive goes to the Trash, permissions are set back. Undo is in the folder's menu, after the change in the status line, and on the Mac in the Edit menu, named after the change ("Undo Move"). SpectaShell remembers your last 100 changes, on every host, in every window. An undo that fails part way keeps what it did, and stays to be tried again.

The Trash#

Move to Trash puts items in the host's own Trash: on Linux the desktop's Trash in your home, on a Mac host the Finder's. Trash, among the places, shows it, with where each item was and when it was deleted.

Put Back returns items to where they were, making their folder again if it is gone. On a Mac host, the Trash keeps no record a host can read, so only Undo puts an item back there.
Delete Immediately… deletes the items for good, after asking.
Empty Trash…, in the folder's menu, deletes everything in it for good, after asking.

An item on another disk than the Trash cannot be moved to it.

Places and favourites#

While SFTP shows a place on the Mac or the iPad, the sidebar lists its places under SFTP, headed by the place's tile and name, and the place's name in the path bar opens them as a menu on every device:

Home, Desktop, Documents and Downloads, the ComfyUI folders in the home, and Computer (/);
Favourites: folders you chose with Add to Favourites. A host's favourites go with it to your other devices. A host of ~/.ssh/config has none.
Trash;
Disks: drives and network shares mounted on the host, or a Mac's volumes.

Drop items on a place to put them there. Right-click a favourite for Remove from Favourites.

On the iPad and iPhone, this device's places are SpectaShell's folder and, under Folders, the folders you add with Add Folder…: iCloud Drive, a USB drive, another app's folder. They stay on this device only. Remove from Folders lets one go.

Two places side by side#

On the Mac and the iPad, Show Two Panes, at the right of the path bar, opens a second pane beside the first. Each of the two then has Close Pane (✕) in its path bar, and in its ⋯ menu: the other pane stays, as the only one. A second pane always starts at Choose a place, so you can open this device beside a host, or two hosts.

Drag items from one pane to the other to copy them there. Between two places they are always copied; the originals stay.
Copy to GPU Box › outputs, in an item's menu, copies it into the folder the other pane shows (Shift-Command and the arrow toward that pane). When both panes show the same place, Move to … moves it there (Option-Shift-Command and the arrow).
A copy between two hosts goes straight from one to the other through SpectaShell, never stored on your device. The status line shows how far it is ("Copying “model.safetensors” — 1.2 GB of 6.9 GB"), with Stop, which removes the part copied.
Two panes on one host copy on the host itself.

The pane you are working in has a coloured line along its top, and its selection is in colour while the other's is grey. The sidebar's places, the path bar's menus, the Edit menu and the keys act on it; Tab goes to the other pane. See In SFTP for every key, Norton Commander's F5 to F8 among them.

The iPhone shows one place at a time: its back button returns to Choose a place.

On the iPhone#

The folder is a list under a large title. Select picks items for the bar at the bottom: Move To…, Copy To…, more in its ⋯, and Trash. Swipe a row to the left to Trash or Rename it — in the Trash, to Delete or Put Back. Pull down to reload.

Viewing and editing text#

Scripts, config files, logs and other text open in SpectaShell's text viewer, in your terminal's font and colours, with line numbers and colours for shell, Python, JSON, YAML, config files, Dockerfiles and logs. A file without an extension is looked at first, to tell text from anything else.

Find searches the file.
Follow shows what the file grows by, as tail -f does. A log opens at its end.
At most 8 MB is read: a file's start, or a log's end, and the viewer says which.
Edit lets you change the file, and Save writes it back to the host. If the file changed on the host since you opened it, you choose: Reload and lose your changes, or Save Anyway. Leaving with changes not saved asks first. A file that is not plain UTF-8 text cannot be edited.
The ⋯ menu has the text size, Go to Top, Go to End, Revert to Saved, and Download to Downloads on the Mac or Share… on the iPad and iPhone.

Port forwarding#

A program on a host listens on a port — ComfyUI on 8188, Jupyter on 8888, TensorBoard on 6006 — that your device cannot reach. Port forwarding opens that port on your device: connections to localhost:8188 here go, over the host's SSH connection, to port 8188 there.

Forwarding a port#

From the status line: the ports a pane's programs listen on show at its right, such as :8188. Click one in a pane on a host to forward it; the Port Forwarding page shows it. A port in a shell on your Mac opens in your browser instead.
From the side panel: its Info lists the shell's listening ports, each with Forward. On the Mac, Show Side Panel (Option-Command-I) opens the panel; on an iPad held sideways, the panel button at the right of the tab strip does.
New Forward, on the Port Forwarding page: choose a host, its Port there, and if you want a port Here and What it is. Save and Start saves it and opens it.

The port here is the host's number when it is free here, else the next free one, and the list says so: "8188 was in use here". A port you name in Here is that one or none. Only your device can use it: the port is open on localhost only, never to your network.

The Port Forwarding page#

Port Forwarding is in the sidebar on the Mac and the iPad; on the iPhone, in Settings, under Connections.

Running now lists the ports open here: the host and its port, what listens there, "→ localhost:8188", how long it has run, Open in Browser, and Stop. A forward that could not start says why, with Dismiss. When nothing answers on the host's port, the forward says so and stays, as the program may be about to start.
Saved lists the forwards you saved, each with Start, Edit, and a switch that starts it with the host's first connection on each of your devices. Saved forwards go to your other devices with their host. Delete Forward, in a forward's editor, deletes it on every device; a port open now stays open until you stop it.

On the Mac, Open in Browser opens your default browser. On the iPad and iPhone it opens Safari inside SpectaShell, since leaving for Safari would stop the forward.

On the iPad and iPhone, forwards run only while SpectaShell is on the screen. They stop when you switch away, and start again, at the same ports, when you come back; the page says so in a banner.

Pages beside a shell#

A page a shell's programs serve can open in a pane beside the shell, in the same tab: the notebook or the dev server and the shell that runs it, side by side, on the Mac, the iPad and the iPhone.

Opening a page#

A link a shell prints to its own machine — http://localhost:8188, http://127.0.0.1:3000, http://0.0.0.0:8888/lab — opens beside it when you open the link (see Working in the terminal). It is that host's port, not your device's.
Open Page Beside, in the menu of a port in the status line (a right-click, or a touch and hold).
The globe in the tab strip, on the Mac and the iPad, lists Ports of This Shell, each of which opens beside the shell, and Web Page, a blank page with its address field ready.
Open Location… (Command-L) puts you in the address field of the page you are using, or opens a blank Web Page beside the pane you are in.

The address field takes an address, or words to search for: those go to the engine chosen in Settings under Shell ▸ Search With — Google at first, or DuckDuckGo, Bing or Ecosia.

A page of a host comes over a forward of its port, which the page starts if none runs, and stops when its last page closes; a forward you started yourself runs on. A page of your Mac's own shell loads the address as printed. A page is a pane like any other: it splits, resizes and comes back with its tab when you open SpectaShell again. On the iPhone it is shown one at a time, as a pane is (see On the iPad and iPhone).

The page's bar#

Back, Forward, and Reload, which is Stop Loading while the page loads.
The address field: the host's name, then the address as the shell printed it (http://localhost:8188/lab). Type an address, or words to search for, and press Return. An address of the host's loopback opens that host's port.
What the page last downloaded, such as "Saved report.csv to Downloads" (on the iPad and iPhone, "to the SpectaShell folder in Files").
Open in Browser opens the page in your browser: on the Mac your default browser, on the iPad and iPhone Safari inside SpectaShell.
Close Page.

When a page cannot show — its forward stopped, the server is not running — it says why, with Try Again.

Going anywhere from a page#

The pane is a browser. Links, redirects and addresses you type go where they lead, in the same pane: a sign-in at another site, the documentation, the server once it is deployed. A window the page opens opens in the same pane too.

An address on localhost always means the host of the shell the page is beside, as it does for the shell. So a sign-in that sends you back to http://localhost:3000/callback comes back to the dev server on the host, and a link to another of its ports opens that port in the page's place. A mailto: link goes to your mail app.

Each host's pages keep their own cookies and sign-ins, apart from every other host's and from pages of the web, so a sign-in to one host's server is never handed to another's. Downloads go to the Mac's Downloads folder, or on the iPad and iPhone to SpectaShell's folder in Files.

Web links from a shell#

A web address a shell prints — https://github.com/… — opens in a page beside it, or in your browser, as Open Web Links Beside the Shell says, in Settings under Shell. It is on at first on the iPad and iPhone, where going to Safari and back is what the page spares you, and off on the Mac.

Pages and coding agents#

A coding agent in a kept shell — Claude Code or Codex on a GPU box, or on your Mac — can use the pages beside its shell: open the dev server it started, read the page, click and type in it, read its console, run JavaScript and take a picture of it, on the same page you see. It reaches your device only through the shell's own connection; nothing listens on a port.

Setting it up#

In Settings, Pages for Agents — the Agents tab of SpectaShell ▸ Settings… on the Mac — lists the commands to copy. Run one once in a shell where the agent runs:

# Claude Code, on a host whose shells are kept
claude mcp add --scope user spectashell -- ~/.local/share/spectashell/current/spectashell-keeper mcp

# Codex, on a host whose shells are kept
codex mcp add spectashell -- ~/.local/share/spectashell/current/spectashell-keeper mcp

# Any other agent: the page command and what it does
~/.local/share/spectashell/current/spectashell-keeper page --help

On the Mac, Settings gives the same commands for this Mac, with the path of the program in SpectaShell itself. A host whose shells are not kept has no keeper program, and so no pages for agents (see Shells that keep running).

What an agent may do#

Only pages of its own host's ports. An agent opens pages of http://localhost:PORT on the machine it runs on, beside its own shell, in the tab you have it open in. It cannot open a page of the web, and it cannot use a page that went to another site — a sign-in, a link — until the page is back at its port.
You see it. While an agent uses a page, the page's bar says so — "Claude Code is using this page" — and each element it acts on is outlined for a moment. A page an agent opens does not take the keyboard from you.
Stop in that bar keeps agents off the page: its bar says "Agents stopped", and every command to it is refused until you choose Allow.
Downloads ask first. A page an agent has used asks before it saves a download ("Save “report.csv” to This Mac?"), for as long as it is open: what a page tells an agent is not yours, and a page can ask the agent to fetch a file. Choose Save or Don't Save.

To keep a host's agents off this device's pages altogether, choose Keep Agents Off Pages in the host's menu; Let Agents Use Pages lets them back. It is on at first, and the choice is this device's own: it is not synced. The menu offers it while the host's shells are kept.

Good to know#

Nothing a page says is checked for an agent: a page, or text someone put in it, can tell the agent what to do. Watch what an agent does on a page, and use Stop when it goes somewhere you did not expect.
The file manager does not save what it showed: a window opened again starts at Choose a place.
Between two places, items are always copied, never moved; delete the originals yourself when you mean to move them.
Favourites and saved forwards belong to hosts of your book; a host from ~/.ssh/config has neither.
A page beside a shell has no tabs, bookmarks or saved passwords; Open in Browser takes it to your browser for those.