# Settings and troubleshooting.

Change window settings and outside-link permissions. Check the Porthole output channel when a command or link does not work.

## Window settings.

Open VS Code Settings and search for `porthole`. Every setting in this table begins with `porthole.`

Window and preview defaults

| Setting | Default | Purpose |
| --- | --- | --- |
| `sizes` | 420×640, 480×720, 640×900 | Opening size and cycle sequence. |
| `position` | `null` | Opening coordinates; otherwise center on the current window. |
| `compact` | `true` | Hide tabs, breadcrumbs, and the status bar. |
| `alwaysOnTop` | `true` | Open pinned above other windows. |
| `markdown.colorScheme` | `auto` | Follow VS Code’s theme, or choose `light` or `dark`. |
| `keepToOneTab` | `move` | Handle editors opened by other extensions; also accepts `ask` or `off`. |
| `askToKeepCompact` | `true` | Offer VS Code’s one-tab configuration at first pop-out in a session. |
| `useInternalCommand` | `true` | Use the internal command for exact preset sizing. |

## Outside-link permissions.

These names begin with `porthole.outsideLinks.` They control links sent from a terminal, a script, or an agent.

Outside-link defaults

| Setting | Default | Effect |
| --- | --- | --- |
| `enabled` | `true` | Accept outside links at all. |
| `actions.open` | `true` | Allow links to open pages. |
| `actions.installSkill` | `true` | Allow skill-installation links, with permission remembered for the receiving VS Code workspace. |
| `allowWorkspaceFolders` | `true` | Allow files in the receiving window’s workspace folders without asking. |
| `allowedFolders` | `[]` | Additional folders, by absolute path, whose files may open without asking. |
| `allowLocalFiles` | `false` | Allow other local files without asking. |

Folder checks resolve `..` and symbolic links before comparing paths. Comparisons ignore letter case on macOS and Windows.

Turn `porthole.outsideLinks.enabled` off to disable the whole interface. The action settings let you control page opening and skill installation separately.

## Review what changed.

**Porthole: Review and Reset Settings…** lists user settings set by or for Porthole. Select the entries you want to remove. Porthole also announces each change it makes to a setting, with a button to open it.

## The size is wrong, or cycling does nothing.

Exact sizing relies on `_workbench.openWith`, an internal VS Code command rather than a documented API. VS Code can change or remove it without notice.

If the call fails or Porthole detects no new window, it tries opening the page through separate commands. This fallback does not apply your requested size. Check the **Porthole** output channel if no window appears.

Set `porthole.useInternalCommand` to `false` to skip `_workbench.openWith` and use this fallback for new windows. Size presets then do not apply.

## An outside link does nothing.

1. Keep VS Code running and check that Porthole is installed. Outside links require 0.3.0 or later; skill installation requires 0.4.0.
2. Check that the local file exists and that its extension is supported.
3. Check the receiving VS Code window. A relative path is resolved only inside that window’s workspace folders.
4. Read the **Porthole** output channel. Refusals explain disabled settings, missing files, and ambiguous relative paths.

If a permission question is waiting, answer it before sending the link again. [Terminal and agents](https://jlumbroso.github.io/porthole-docs/terminal-and-agents.html) covers parameters, encoding, and repeat opens.

## A Markdown checkbox will not tick.

This is VS Code’s read-only Markdown preview. Use an HTML checklist when the page needs to respond to clicks or other input.

## Paste or text shortcuts do not work.

On macOS, **Cmd+V** does not paste into a page while the floating window has focus. Use **right-click → Paste**.

**Ctrl+A** and **Ctrl+E** also do not move to the start and end of a line in integrated-browser text fields. These limits were traced to VS Code.

## Report a problem.

Include your VS Code version and the **Porthole** output in a [bug report](https://github.com/jlumbroso/porthole/issues/new/choose). If you use an older VS Code release, first try the latest version.

Porthole has been run on macOS, with VS Code 1.134.0 and 1.141.0. Windows and Linux remain untested. The [version-floor record](https://github.com/jlumbroso/porthole/blob/v0.4.0/docs/release/VERSION-FLOOR.md) distinguishes source inspection from hands-on checks.

## Chapter notes

**Find the settings**

Open VS Code Settings and search for porthole. The tables show the defaults shipped in Porthole 0.4.0.

**Read Porthole’s logs**

Open VS Code’s Output panel and select Porthole. Refused links and internal-command fallbacks are reported there.

**When reporting a problem**

Include your VS Code version and the Porthole output. If you use an older VS Code release, first try the latest version.

For Porthole 0.4.0. Updated 19 October 2026. [Online chapter](https://jlumbroso.github.io/porthole-docs/settings-and-troubleshooting.html). [Source reference](https://github.com/jlumbroso/porthole/blob/v0.4.0/package.json).