From a folder
to a finished page.

Astrolay edits local Astro projects. Your source files stay on your computer. GitHub stores the revisions you push; Cloudflare hosts the releases you publish.

1. Open the workspace

Launch Astrolay.app. It starts the local project service automatically; you do not need to start a development server for Astrolay itself. Git must be installed for version control. On macOS, installing the Apple command line tools provides Git.

You can also use the browser workspace while the desktop app is open. Allow local network access if your browser asks. Connections can be managed without a local project service, but editing and builds require the companion.

2. Connect your accounts

1. Open Connections and choose Connect GitHub. Sign in and approve Astrolay.
2. Use Manage repository access to install the GitHub App and select the repositories it can use.
3. Choose Connect Cloudflare and authorize the account you will publish to.

Astrolay saves an account session. Provider access and refresh tokens are encrypted in the account service. You do not paste API keys into project files. Reauthorization is needed if a session expires or access is revoked.

3. Bring a site

• New project: choose a new folder to create a minimal Astro site.
• Open folder: select the folder containing an Astro package.json.
• Clone repository: select an authorized GitHub repository and a new local destination.

Choose Install dependencies, then Start preview. Only open projects you trust: installing dependencies and running Astro executes that project’s code. npm projects with a committed package-lock.json are supported for releases.

4. Edit the actual source

Select an element in the canvas or Navigator. Use the inspector for text, attributes, layout, spacing and typography. The canvas fills the available area and scrolls normally. Switch to Interact to follow links and test the site.

• Desktop changes are the base. Tablet overrides apply at 991px and below; mobile overrides at 479px and below.
• Use Structure to insert, reorder, duplicate or remove supported static elements.
• Open a CSS file in Styles to edit reusable classes and :root design tokens.
• Upload images and fonts from Assets, then copy their public paths into attributes.
• Use Source for dynamic expressions, scripts, component structure or unsupported syntax. Save with ⌘S / Ctrl+S.

Edits use revision checks. External saves refresh automatically when there is no local draft. If you have unsaved Source edits, Astrolay retains them and asks you to review the conflict before saving. Files with parse errors remain accessible in Source. Undo history survives restarts. Unsaved buffers in other editors cannot be detected. Save those buffers before editing the same file in Astrolay.

5. Keep a checkpoint

In Version control, review changed files, select what belongs in your commit, and write a message. Add an existing GitHub remote or create a repository if your GitHub App permissions allow it. Push sends the committed branch to GitHub. Use Verify GitHub checkpoint to check the remote commit, especially after a lost connection. Pull only fast-forwards; resolve divergent branches in your Git client.

Repository creation needs GitHub repository Administration write permission. If you prefer a smaller permission set, create the repository on GitHub and add its HTTPS URL in Astrolay.

6. Preview, then publish

1. In Publish, choose a Cloudflare account and Pages project, then save the destination.
2. Commit all changes and the lockfile. Select Build committed revision.
3. Select Deploy preview. Wait for Cloudflare to report success and open its preview URL.
4. Choose Publish on that preview and confirm the production change. The exact preview files are reused.
5. To undo a release, choose Restore on an earlier successful production deployment.

Current publishing supports static HTML builds in dist/. Server-rendered Astro adapters, Functions, environment-specific builds, and monorepo package roots need a separate deployment workflow.

When something needs attention

Activity survives workspace reloads. If the local service stops mid-operation, the job is marked interrupted and is never repeated automatically. Check the actual GitHub checkpoint or deployment history before retrying. Current production reports Cloudflare’s active deployment, including after a rollback.

• Local service unavailable: open Astrolay.app and refresh projects. For source development, npm start starts both services.
• Preview stopped: inspect Activity, install missing dependencies and restart the preview.
• File changed outside Astrolay: copy any unsaved draft you need, then reload and review the current file.
• Account connection failed: close old authorization popups and start a fresh connection. Use Refresh status after authorization.
• Interrupted source edit: use the recovery banner to review the affected file. Keeping the disk version archives both versions first.
• Build failed: read Activity. Resolve the Astro error, commit the fix, then build again.
• Cloudflare access declined: start a fresh connection and choose an account you have permission to publish to.

Release boundaries

Version 0.1 supports a local workflow for static Astro sites. It does not yet provide remote cloud development containers, live team collaboration, built-in merge conflict resolution, a CMS, signed automatic desktop updates, or a signed public installer. These are separate product work and should not be represented as completed.