MaritimeFS

Your Maritime agents, right inside VS Code.

Browse a Maritime agent's persistent volume in the standard Explorer, open files in the native editor, and save changes directly to the agent. Use native commands to run a one-shot process, inspect recent logs, or manage its lifecycle.

MaritimeFS is an independent MIT-licensed community extension, unaffiliated with Maritime. It uses the official Maritime TypeScript SDK. Marketplace publication is pending; the current candidate is 0.1.2, packaged for the Marketplace pre-release channel.

What works

• Password-masked API key input and VS Code SecretStorage; reconnect without restarting.
• Native Maritime Activity Bar view with account-visible agents and status.
• A case-sensitive maritime://<agent-id>/<volume-root>/... filesystem: directory browsing, text and binary reads/writes, creation, mkdir, rename, and confirmed deletion.
• Native editor saving with best-effort byte-based conflict detection.
• Explicit workspace opening, refresh, and locking. Restored workspaces cannot initiate file requests until unlocked again.
• Non-interactive command execution with structured argv, stdout/stderr and exit codes.
• Wake, sleep, restart, status refresh, and up to 100 recent historical log entries.
• Unit tests, real VS Code Extension Host tests, and production VSIX packaging. Simulation is confined to a separate development build.

Live verification: On 2026-10-21, an explicitly approved single ZeroClaw agent passed real authentication/discovery, native workspace editing and save/readback, binary and empty-file handling, case-sensitive names, conflict refusal, rename/delete, one pwd, historical logs, sleep, and declined-wake checks. Test files were removed and the agent was left sleeping. Explicit start/restart endpoints and Cursor remain unverified. See the acceptance record.

Demo workflow

Watch or download the 59-second demo: open an agent workspace, browse and edit a remote configuration, save, and run a command on the same agent. The real output verifies the updated routing rules with exit code 0. The example uses synthetic ticket data and makes no model calls.

The demo guide reproduces the example in a separate workspace. See the recording script, publication drafts, and asset details. The recording demonstrates an earlier build; see version-specific release notes for the latest verification scope.

Quick start

Requires desktop VS Code 1.105 or newer and an existing Maritime agent. No local Maritime CLI is required to run the extension.

1. Build or obtain maritimefs-0.1.2.vsix:

   npm ci
   npm run package:prerelease
   code --install-extension maritimefs-0.1.2.vsix
   

   Alternatively use Extensions → ⋯ → Install from VSIX…. Development requires Node.js 22.13+ or Node.js 24 LTS.

2. Create a personal API key in Maritime Settings or with the official CLI: maritime keys create --name maritimefs. Check key scopes; execution needs deploy. Use a key that can access your Agents, not a Computers-only key.

3. Open the Maritime Activity Bar view and run MaritimeFS: Connect Account. Paste the key into the secure input. MaritimeFS validates it with an agent-list request before storing it.

4. Select an agent's Files, or run MaritimeFS: Open Agent Workspace. A sleeping agent requires confirmation before any file call. The actual persistent-volume root comes from the API; it is not assumed to be /workspace.

5. Files switches to the standard Explorer and selects the agent's remote folder. Expand it, open a file, edit, and press Cmd+S / Ctrl+S. Reopen or refresh to inspect the persisted content. You can also open Explorer with Cmd+Shift+E / Ctrl+Shift+E.

VS Code can restart its Extension Host when converting an empty/single-folder window to a workspace. If Explorer reports that access is locked after that restart, run Open Agent Workspace again. For uninterrupted setup, start from a saved multi-folder workspace. Requiring a fresh open after restarts prevents restored workspaces from waking agents.

The account key and workspace access have separate lifetimes. A stored key restores automatically; you only need to reopen the workspace after a restart. The Maritime: Open Workspace status item means your account is connected but file access is locked. If secure storage temporarily fails, use Restore Saved Connection to retry without pasting your key. If no saved key is found, check that you are using the same VS Code installation/profile and that the OS keychain is available.

Commands and everyday use

All commands are available through the Command Palette under MaritimeFS. Agent context menus contain the relevant operations.

To execute a command, choose an agent and enter a JSON argv array:

["pwd"]

Arguments retain their boundaries; the extension does not concatenate them into a shell command. For deliberate shell behavior you may explicitly run ["sh", "-lc", "your command"]. Commands use the agent's default working directory, which may differ from its volume. Submission can wake a sleeping agent and requires consent. Commands are never retried automatically. A timeout or lost connection does not establish whether remote work stopped; inspect before resubmitting.

The command runner and logs use VS Code Output Channels. They do not provide an interactive shell or simulated streaming. The status item appears while credentials are configured and lets you select an agent; use Connection Status for a fresh authentication check.

Filesystem and security boundaries

• Keys belong only in VS Code SecretStorage. The extension does not read .env, import CLI credentials, upload local folders, or collect telemetry.
• Downloads and mutations are confined lexically to the API-discovered persistent volume. Root deletion and cross-agent moves are refused. Known symlink metadata is rejected, but the current API provides no lstat/realpath: canonical protection against symlink escapes depends on Maritime's server. Use this extension on trusted agent volumes.
• Saves compare SHA-256 hashes of the last read and fresh remote bytes. There are no documented conditional writes, so a concurrent writer can still win between the check and upload. New-file creation also has a race. This is not atomic conflict safety. Prefer one editor per file.
• If a save conflicts, copy your unsaved edits somewhere safe, reopen the remote file, and merge deliberately. The extension refuses to overwrite an unread existing file; it keeps at most 256 hash baselines and may require rereading after eviction.
• Files are limited to 8 MiB to bound extension-host memory. Directory responses are capped at 4 MiB; no recursive preloading or directory pagination is invented. Percent signs, control characters, backslashes, and parent traversal segments in remote paths are rejected.
• Writes, delete, rename, mkdir, execution, and lifecycle actions require workspace trust. Deletes always require provider-level confirmation; rename never replaces an existing destination, even when overwrite was requested.
• There is no filesystem polling or remote watch stream. Successful local mutations emit events; use manual refresh for external changes. Every authorized file operation checks status first. An agent could still fall asleep between that check and a file request: upstream has no no-wake request option. File access approval therefore permits that remaining race.
• Explorer metadata is reused for up to two seconds to reduce repeated directory requests. Refresh bypasses it, and mutations invalidate it. File contents and save conflict checks always use fresh remote bytes. Maritime response time and cold wakes still affect latency; fewer extension requests do not guarantee a particular response time.

See security decisions and API research.

The current pre-release candidate is 0.1.2. See its release notes and the publication guide. Maintainers freeze a reviewed Marketplace candidate with npm run release:freeze:prerelease, then verify that exact archive with npm run release:verify. The frozen VSIX, checksum, source manifest, and validation report live under release-artifacts/0.1.2/; ordinary rebuilds do not overwrite them. Freezing does not publish anything.

Development and tests

Installed VSIX builds use only the official SDK and SecretStorage. They contain no mock backend or simulation setting; old maritimefs.mode settings are ignored. Real API failures never switch to simulated data.

Contributors can run npm run build:dev, then press F5 to launch the separate development extension under .vscode-test/development-extension. It defaults to clearly labeled SIMULATED agents with ephemeral credentials/files. This build cannot run as an installed production extension and never overwrites dist/extension.cjs. To deliberately debug a real connection in a Development Host, launch it with MARITIMEFS_DEV_REAL=1; the installed VSIX ignores this environment variable. Default automated tests use simulation; live tests remain explicitly opt-in.

npm ci
npm run typecheck
npm run lint
npm run format:check
npm test
npm run build
npm run test:integration
npm run package
npm run verify:package
npm audit --omit=dev

Press F5 to launch an Extension Development Host. Default integration tests use @vscode/test-electron, an isolated VS Code profile, and mocks. Separately, npm run test:live is explicitly opt-in for one approved agent; see the development guide. They download VS Code 1.105.1 by default; set VSCODE_TEST_VERSION=stable for current stable, or VSCODE_EXECUTABLE_PATH for another compatible executable. On Linux run xvfb-run -a npm run test:integration. CI tests Node 22/24 and VS Code minimum/current stable without Maritime secrets.

Architecture: extension.ts wires SecretStorage, the typed SDK adapter, access sessions, agent service/tree, filesystem provider, commands, and Output Channels. The framework-independent RemoteVolume implements file behavior and conservative conflict checks. Only the API adapter performs network operations. See architecture and development guide.

Compatibility and limitations

Cursor can install a VSIX and use these stable VS Code APIs if its embedded VS Code version meets the minimum requirement. Cursor itself has not been tested in this environment. Browser VS Code is not supported; remote language tooling, debug adapters, terminals and Git features may require real local disk paths and will not automatically work in a virtual workspace. This MVP helps inspect/debug through files, commands and logs; it is not a Remote SSH environment or a debugger adapter.

Computers are a separate Maritime product and API and are not integrated. There is no agent creation/deletion, sync, search provider, detached-job UI, live log stream, or automatic billing change.

Troubleshooting

Contributing and roadmap

Read CONTRIBUTING.md. Changes need focused tests, strict TypeScript, clean lint/format checks, and no credentials. Keep real API tests opt-in and limited to one approved agent.

The highest-value follow-ups are a separately approved explicit start/restart and Cursor acceptance pass; server-supported revisions/conditional writes and canonical symlink metadata; and interactive sessions or filesystem events if Maritime publishes suitable APIs. See the verification record for the exact scope of live validation.

License

MIT. No affiliation with or endorsement by Maritime is implied.