@@ -0,0 +1,158 @@
7+Port is a desktop GUI application that allows you to spin up, access, and manage
8+your Urbit ships without any knowledge of the command line or Urbit binary.
12+- Automatic port forwarding with NAT-PMP.
13+- Boot a new comet, planet, moon or star.
14+- Import an existing pier
15+- Use a ship via its web interface.
16+- Manage and run multiple ships.
17+- Connect to the web interface of a remote ship.
19+- Export a pier in a zip file.
23+Port is available for Linux, MacOS and Windows. See the [Getting
24+Started](/getting-started#port) for installation instructions.
28+With Port freshly installed, you can select `Start without an ID` on its home
29+screen. If Port already has other ships installed, you can navigate to `Home`,
30+drop down the `Boot Menu` and select `Comet`. You'll be presented with the
33+
35+Give your comet a name in the `Name` field. This name is just displayed locally
36+in Port for convenience. Next, hit `Continue`. It'll take a few minutes to spin
37+up the new Comet, then you can click on `Launch Ship into Urbit` and it'll take
38+you to the login screen. Click on `Copy Access Key` at the bottom-left, paste it
39+into the `Access Key` field, and hit `Continue`. You'll now be at your ship's
40+home screen and ready to explore Urbit.
44+**Important: This is for booting a ship for the first time, or for booting a
45+ship which has just undergone a [breach](/docs/glossary/breach). A ship should
46+only be booted from its keyfile in its current
47+[rift](/docs/azimuth/life-and-rift#rift) once. If your ship has already been
48+booted elsewhere, see the [Import pier](#import-pier) section instead.**
50+With Port freshly installed, you can select `Boot a fresh ID` on its home
51+screen. If Port already has other ships installed, you can navigate to `Home`,
52+drop down the `Boot Menu` and select either `Planet`, `Moon` or `Star` depending
53+on the kind of ship you're booting. You'll be presented with a screen that looks
56+
58+Enter a name for your ship in the `Name` field. This name is just displayed
59+locally in Port for convenience. Next, enter your ship's name (e.g.
60+`~sampel-palnet`) in the `Shipname` field. For `Key File`, select `Choose Key File` and browse to its location on your computer. If you don't have your
61+keyfile yet, see _step one_ of the [Setting up your
62+urbit](/getting-started/planet#keyfile) guide. Once you've selected the keyfile,
65+It'll take a few minutes to spin up the ship, then you can click `Launch Ship into Urbit` and it'll take you to the login screen. Click `Copy Access Key` at
66+the bottom-left, paste it into the `Access Key` field, and hit `Continue`.
67+You'll now be at your ship's home screen and ready to explore Urbit.
71+Port can import existing [piers](/docs/glossary/pier). For example, if you've
72+been running your ship with the Urbit binary from the command line, and would
73+now like to run it with Port instead, you can do so.
75+With Port freshly installed, you can hit `See More Options` on the home screen
76+and then `Boot an existing ship`. It should bring up this screen:
78+
80+In the `Name` field, give your ship a name. This name is just displayed locally
81+in Port for convenience. Next, select the type of the ship you're importing from
82+the `Ship Type` drop-down menu. Under `Upload Pier`, click `Choose Directory`,
83+then browse to your pier in the file system.
85+**Important: Make sure you have shut down your pier before trying to import it.**
87+By default, Port will move it into its own directory for piers it manages. If
88+you want to keep it in its current location instead, check the `Keep pier in current directory` checkbox. Finally, hit `Continue` and then `Launch Ship into Urbit` and it'll take you to the login screen. Click `Copy Access Key` at the
89+bottom-left, paste it into the `Access Key` field, and hit `Continue`. You'll
90+now be at your ship's home screen.
94+Rather than running ships locally, Port can also connect to remote ships, for
95+example those running on cloud servers. This simply connects to the web
96+interface of the remote ship, it doesn't move its pier.
98+With Port freshly installed, you can hit `See More Options` on the home screen
99+and then `Access remote ship`. It should bring up this screen:
101+
103+In the `Name` field, give your ship a name. This name is just displayed locally
104+in Port for convenience. Next, enter the full URL (including the `http[s]://`
105+part) of the remote ship's web interface and hit `Continue`. You'll now be at
106+your ship's login screen. Enter your web code and login, you'll now be able to
109+If you want to remove the ship from Port you can go `Home`, hit the `Manage`
110+button for the ship, and select `Remove` under `Ship Migration`. This will
111+remove it from Port and disconnect it from the web interface, but the ship will
112+keep running as usual on the remote host.
116+From the home screen of Port, you can hit `Open` on a ship to access its web
117+interface. When you're in a ship's web interface, you can hit `Home` in the
118+bottom-left to return to the Port home screen.
120+To manage a ship in Port and see details about it, you can hit the `Manage`
121+button for the ship in question on the home screen.
125+To stop a ship in Port, hit the `Manage` button for the ship on the home screen.
126+Then, hit the `Stop` button, and the ship will be shut down. Its status will
127+have changed from `Running` to `Stopped`.
129+To start a ship again, just hit the `Launch` button on the ship's `Manage`
130+screen. It'll automatically open the ship's web interface, and the ship's status
131+will be back to `Running` again.
135+If don't want Port to manage a particular ship any longer, for example if you
136+want to move it to a cloud server, you can export it from Port.
138+From Port's home screen, hit the `Manage` button for the ship in question. Then,
139+under `Ship Migration`, hit the `Eject` button. Port will shut down the ship,
140+remove it from Port and compress its pier into a `.zip` file. It will also open
141+a file browser so you can copy it somewhere else. The location of the `.zip`
142+file will be the path to the pier shown on its `Manage` screen.
144+Once you've moved the `.zip` file to its new location, it can simply be unzipped
145+and started again. If it's being moved to another machine which also runs Port,
146+see the [Import pier](#import-pier) section for details of importing it.
150+**Warning: Deleting a pier is irreversible, and all data will be lost. If the
151+ship is a comet, the comet name will be unusable again. If the ship is a planet
152+or star, you will need to perform a [breach](/docs/glossary/breach) via Bridge
153+to be able to use it again (and all of its data will still be lost).**
155+To completely delete the pier of a ship managed by Port, go to the home screen
156+and click `Manage` for the ship in question. Then, under `Ship Migration`, hit
157+`Delete Permanently` and accept any warnings. The ship's pier will be deleted
158+and it will be removed from Port.